Source: index.js

// #region  F I L E
// <copyright file="mcode-cache/index.js" company="MicroCODE Incorporated">Copyright © 2022-2024 MicroCODE Incorporated Troy, MI</copyright><author>Timothy J. McGuire</author>
// #region  M O D U L E
// #region  D O C U M E N T A T I O N
/**
 *      Project:  MicroCODE MERN Applications
 *      Customer: Internal + MIT xPRO Course
 *      @module   'mcode-cache.js'
 *      @memberof mcode
 *      @created  January 2022-2024
 *      @author   Timothy McGuire, MicroCODE, Inc.
 *      @description >
 *      MicroCODE File and Data Caching Library
 *
 *      LICENSE:
 *      --------
 *      MIT License: MicroCODE.mcode-cache
 *
 *      Copyright (c) 2022-2024 Timothy McGuire, MicroCODE, Inc.
 *
 *      Permission is hereby granted, free of charge, to any person obtaining a copy
 *      of this software and associated documentation files (the "Software"), to deal
 *      in the Software without restriction, including without limitation the rights
 *      to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
 *      copies of the Software, and to permit persons to whom the Software is
 *      furnished to do so, subject to the following conditions:
 *
 *      The above copyright notice and this permission notice shall be included in all
 *      copies or substantial portions of the Software.
 *
 *      THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 *      IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 *      FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 *      AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 *      LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 *      OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 *      SOFTWARE.
 *
 *
 *      DESCRIPTION:
 *      ------------
 *      This module implements the MicroCODE's Common JavaScript functions for data caching.
 *
 *      NOTE:
 *
 *      o  'key' in this code refers to the Application Key or File Path.
 *
 *      o  'cacheKey' in this code refers to a fully qualified cache Key.
 *
 *      o  'cacheKeys' are made from 'key' values by the 'cacheMakeKey()' method,
 *                     which formats the 'key' into a cache Key with a prefix
 *                     based on the current Namespace.
 *
 *      o  '_cache*()' are private methods that are not exposed to the caller,
 *                     these expect 'cacheKey' values, not 'key' values.
 *
 *        <key> - application 'key' format
 *        <namespace>:<key> - 'cacheKey' format
 *
 *      Examples:
 *
 *         key:      '/backend/components/app/tool/tool.template.htmx'
 *         cacheKey: 'GM-GPS-eMITS-UI:backend:components:app:tool:tool.template.htmx'
 *
 *         key:      'myKey'
 *         cacheKey: 'MicroCODE:myKey'
 *
 *
 *      REFERENCES:
 *      -----------
 *      1. MIT xPRO Course: Professional Certificate in Coding: Full Stack Development with MERN
 *
 *      2. MicroCODE JavaScript Style Guide
 *         Local File: MCX-S02 (Internal JS Style Guide).docx
 *         https://github.com/MicroCODEIncorporated/JavaScriptSG
 *
 *
 *
 *
 *      MODIFICATIONS:
 *      --------------
 *      Date:         By-Group:   Rev:    Description:
 *
 *      30-Jan-2024   TJM-MCODE  {0001}   New module for common reusable JavaScript data caching functions.
 *      01-Feb-2024   TJM-MCODE  {0002}   Changed to the Universal Module Definition (UMD) pattern to support AMD,
 *                                        CommonJS/Node.js, and browser global in our exported module.
 *      15-Sep-2024   TJM-MCODE  {0003}   Extended to support *node-cache* package for caching local information
 *                                        to avoid network latency, this is now the default cache provider.
 *      26-Aug-2026   TJM-MCODE  {0004}   Added immutable namespace handles and native Redis 8.4+ contracts for
 *                                        typed values, transactions, geo, generation reset, and pub/sub.
 *
 *
 *
 *
 * NOTE: This module follow's MicroCODE's JavaScript Style Guide and Template JS file, see:
 *
 *       o  https://github.com/MicroCODEIncorporated/JavaScriptSG
 *       o  https://github.com/MicroCODEIncorporated/TemplatesJS
 *
 * ...be sure to check out the CTRL-SHIFT+K, +L, +J keybaord shortcuts in Visual Studio Code
 *    for taking advance of the #regions in this file and our templates.
 *
 */

// #endregion
// #endregion
// #endregion

/**
 * @namespace mcode
 * @desc MicroCODE namespace containing reusable package classes and functions.
 */

// #region  I N C L U D E S

const _log = require('mcode-log');

const path = require('path');
const fs = require('fs').promises;

const Redis = require('redis');
const NodeCache = require('node-cache');

// #endregion

// #region  C O N S T A N T S

// MicroCODE: define this module's name for our 'mcode-log' package
const MODULE_NAME = 'mcode-cache.js';

// #endregion

// #region  C L A S S

/**
 * @class cache Class to provide transparent data caching for MicroCODE applications.
 * @memberof mcode
 */
class cache
{
    // #region  C O N S T A N T S

    static CACHE_TTL = 60 * 60 * 24;  // 24 hours in seconds
    static REDIS_URL = null;
    static REDIS_PORT = null;
    static REDIS_USER = null;
    static REDIS_PASSWORD = null;
    static REDIS_MIN_VERSION = '8.4.0';
    static REDIS_VALUE_PREFIX = 'MCACHE1:';
    static MAX_NAMESPACE_BYTES = 64;
    static MAX_LOGICAL_KEY_BYTES = 512;
    static MAX_CHANNEL_BYTES = 256;
    static MAX_VALUE_BYTES = 5 * 1024 * 1024;
    static TRANSACTION_DELETE_BATCH_SIZE = 100;
    static INFO_SECTIONS = Object.freeze(new Set([
        'server',
        'clients',
        'memory',
        'persistence',
        'stats',
        'replication',
        'cpu',
        'cluster'
    ]));
    static GEO_UNITS = Object.freeze(new Set(['m', 'km', 'mi', 'ft']));
    static REDIS_STATUS = Object.freeze({
        NOT_CONFIGURED: 'not configured',
        IDLE: 'idle',
        CONNECTING: 'connecting',
        CONNECTED: 'connected',
        DISCONNECTED: 'disconnected'
    });
    static ERROR_CODES = Object.freeze({
        CONFIG_REQUIRED: 'CACHE_CONFIG_REQUIRED',
        INVALID_CONFIG: 'CACHE_INVALID_CONFIG',
        INVALID_NAMESPACE: 'CACHE_INVALID_NAMESPACE',
        INVALID_TYPE: 'CACHE_INVALID_TYPE',
        NAMESPACE_CONFLICT: 'CACHE_NAMESPACE_CONFLICT',
        NAMESPACE_NOT_FOUND: 'CACHE_NAMESPACE_NOT_FOUND',
        INVALID_KEY: 'CACHE_INVALID_KEY',
        INVALID_CHANNEL: 'CACHE_INVALID_CHANNEL',
        ALREADY_PREFIXED: 'CACHE_ALREADY_PREFIXED',
        VALUE_UNSUPPORTED: 'CACHE_VALUE_UNSUPPORTED',
        VALUE_TOO_LARGE: 'CACHE_VALUE_TOO_LARGE',
        VALUE_FORMAT: 'CACHE_VALUE_FORMAT',
        REDIS_REQUIRED: 'CACHE_REDIS_REQUIRED',
        REDIS_CAPABILITY: 'CACHE_REDIS_CAPABILITY',
        REDIS_VERSION: 'CACHE_REDIS_VERSION',
        REDIS_MODE: 'CACHE_REDIS_MODE',
        DISABLED: 'CACHE_DISABLED',
        INVALID_OPTIONS: 'CACHE_INVALID_OPTIONS',
        INVALID_PATTERN: 'CACHE_INVALID_PATTERN',
        SCAN_LIMIT: 'CACHE_SCAN_LIMIT',
        INVALID_MEMBER: 'CACHE_INVALID_MEMBER',
        INVALID_COORDINATE: 'CACHE_INVALID_COORDINATE',
        INVALID_SCORE: 'CACHE_INVALID_SCORE',
        TIMEOUT: 'CACHE_TIMEOUT',
        OUTCOME_UNKNOWN: 'CACHE_OUTCOME_UNKNOWN',
        TRANSACTION_CLOSED: 'CACHE_TRANSACTION_CLOSED',
        TRANSACTION_DEFERRED: 'CACHE_TRANSACTION_DEFERRED',
        TRANSACTION_COMMAND: 'CACHE_TRANSACTION_COMMAND',
        TRANSACTION_PLAN: 'CACHE_TRANSACTION_PLAN',
        WATCH_CONTENTION: 'CACHE_WATCH_CONTENTION',
        GENERATION_GUARD: 'CACHE_GENERATION_GUARD',
        GENERATION_LIMIT: 'CACHE_GENERATION_LIMIT',
        GENERATION_VERIFY: 'CACHE_GENERATION_VERIFY',
        SUBSCRIBER_CLOSED: 'CACHE_SUBSCRIBER_CLOSED'
    });

    // #endregion

    // #region  P R I V A T E   F I E L D S

    // node-cache instance
    #cache = null;
    #cacheTTL = cache.CACHE_TTL;
    #cacheNamespace = '';
    #cacheNamespaces = [];

    // Redis instance
    #redis = null;
    #redisURL = cache.REDIS_URL;
    #redisPort = cache.REDIS_PORT;
    #redisUser = cache.REDIS_USER;
    #redisPassword = cache.REDIS_PASSWORD;
    #redisConnected = false;
    #redisContexts = new Map();
    #namespaceHandles = new Map();
    #multiOperations = new WeakMap();

    // #endregion

    // #region  C O N S T R U C T O R

    /**
     * @constructor
     * @desc Creates or returns the singleton cache instance.
     * @returns {cache} the singleton cache instance.
     */
    constructor ()
    {
        // Create a Singleton instance
        if (!cache.instance)
        {
            this.#cacheTTL = cache.CACHE_TTL;
            this.#redisURL = cache.REDIS_URL;
            this.#redisPort = cache.REDIS_PORT;
            this.#redisUser = cache.REDIS_USER;
            this.#redisPassword = cache.REDIS_PASSWORD;

            this._cacheInit();

            // add the default namespace as a node-cache namespace
            this.addNamespace({name: 'MicroCODE', type: 'node'});

            // make it current
            this.#cacheNamespace = 'MicroCODE';

            cache.instance = this;
        }

        _log.done(`mcode-cache initialized with namespace: ${this.#cacheNamespace}`, MODULE_NAME);

        return cache.instance;
    }

    // #endregion

    // #region  P R O P E R T I E S

    /**
     * @property {boolean} cacheReady whether the cache instance and configured Redis namespaces are ready.
     */
    get cacheReady()
    {
        if (this.#redisContexts.size > 0)
        {
            return this.#cache != null &&
                Array.from(this.#redisContexts.values()).every(context =>
                    context.status === cache.REDIS_STATUS.CONNECTED);
        }

        return this.#cache != null;
    }

    /**
     * @property {number} cacheTTL the cache Time-To-Live property, in seconds.
     */
    get cacheTTL()
    {
        return this.#cacheTTL;
    }

    /**
     * @property cacheTTL
     * @memberof mcode.cache
     * @desc Sets the default cache Time-To-Live in seconds.
     * @param {number} value the cache Time-To-Live in seconds.
     * @returns {void}
     */
    set cacheTTL(value)
    {
        this.#cacheTTL = value;
    }

    /**
     * @property {array} cacheNamespaces returns an array containing all the namespaces defined in the cache server.
     * The array contains objects with name, type (node or redis), enabled properties, and current statistics for each namespace.
     */
    get cacheNamespaces()
    {
        // Update statistics for each namespace before returning
        this._updateNamespaceStatistics();
        return this.#cacheNamespaces;
    }

    /**
     * @property {string} cacheNamespace the 'prefix' used to group our keys in the cache Server.
     * This property switches to a new namespace, to be used for all subsequent cache operations as the default.
     * The namespace must already exist in the cache servers 'namespace' list, see addNamespace().
     */
    get cacheNamespace()
    {
        return this.#cacheNamespace;
    }

    /**
     * @property cacheNamespace
     * @memberof mcode.cache
     * @desc Sets the default namespace for subsequent singleton cache operations.
     * @param {string} value the registered namespace name.
     * @returns {void}
     */
    set cacheNamespace(value)
    {
        this.#cacheNamespace = value;
        _log.success(`Switched to namespace: '${this.#cacheNamespace}`, MODULE_NAME);
    }

    /**
     * @property {string} redisURL the URL to the Redis Server.
     */
    get redisURL()
    {
        return this.#redisURL;
    }

    /**
     * @property redisURL
     * @memberof mcode.cache
     * @desc Sets the legacy Redis server URL.
     * @param {string} value the Redis server URL.
     * @returns {void}
     */
    set redisURL(value)
    {
        this.#redisURL = value;
    }

    /**
     * @property {string} redisPort the PORT to the Redis Server.
     */
    get redisPort()
    {
        return this.#redisPort;
    }

    /**
     * @property redisPort
     * @memberof mcode.cache
     * @desc Sets the legacy Redis server port.
     * @param {string|number} value the Redis server port.
     * @returns {void}
     */
    set redisPort(value)
    {
        this.#redisPort = value;
    }

    /**
     * @property {string} redisUser the User to the Redis Server.
     */
    get redisUser()
    {
        return this.#redisUser;
    }

    /**
     * @property redisUser
     * @memberof mcode.cache
     * @desc Sets the legacy Redis username.
     * @param {string} value the Redis username.
     * @returns {void}
     */
    set redisUser(value)
    {
        this.#redisUser = value;
    }

    /**
     * @property {string} redisPassword the Password to the Redis Server.
     */
    get redisPassword()
    {
        return this.#redisPassword;
    }

    /**
     * @property redisPassword
     * @memberof mcode.cache
     * @desc Sets the legacy Redis password.
     * @param {string} value the Redis password.
     * @returns {void}
     */
    set redisPassword(value)
    {
        this.#redisPassword = value;
    }

    // #endregion

    // #region  M E T H O D S – P U B L I C

    /**
     * @function addNamespace
     * @memberof mcode.cache
     * @desc Adds a new namespace to the cache server.
     * @param {object} namespace the namespace and configuration to be added to the cache server.
     * @returns {object} the immutable namespace handle.
     * @api public
     * @example
     *     const namespace = {name: 'MicroCODE', type: 'node', user: 'username', password: '...'};
     */
    addNamespace(namespace)
    {
        if (namespace && typeof namespace === 'object' && namespace.name && namespace.type)
        {
            const existingType = this._getNamespaceInfo(this._validateNamespaceName(namespace.name));
            if (existingType && existingType.type !== namespace.type)
            {
                throw this._cacheError('CACHE_NAMESPACE_CONFLICT',
                    `Namespace '${namespace.name}' is already registered as '${existingType.type}'.`);
            }
        }

        const config = this._normalizeNamespaceConfig(namespace);
        const existingNamespace = this._getNamespaceInfo(config.name);

        if (existingNamespace)
        {
            if (existingNamespace.type !== config.type)
            {
                throw this._cacheError('CACHE_NAMESPACE_CONFLICT',
                    `Namespace '${config.name}' is already registered as '${existingNamespace.type}'.`);
            }

            if (config.type === 'redis')
            {
                const context = this.#redisContexts.get(config.name);
                if (!context || context.signature !== this._redisConfigSignature(config) ||
                    context.config.clientFactory !== config.clientFactory)
                {
                    throw this._cacheError('CACHE_NAMESPACE_CONFLICT',
                        `Namespace '${config.name}' is already registered with different Redis configuration.`);
                }
            }

            return this._createNamespaceHandle(config.name);
        }

        this.#cacheNamespaces.push({
            name: config.name,
            type: config.type,
            enabled: true,
            hits: 0,        // Number of successful cache retrievals
            misses: 0,      // Number of failed cache retrievals (key not found/expired)
            keys: 0,        // Current number of keys in cache
            ksize: 0,       // Current key size in bytes
            vsize: 0        // Current value size in bytes
        });

        if (config.type === 'redis')
        {
            const context = this._createRedisContext(config);
            this.#redisContexts.set(config.name, context);

            if (this.#redisContexts.size === 1)
            {
                this.#redisURL = config.url;
                this.#redisPort = new URL(config.url).port || null;
                this.#redisUser = config.username;
                this.#redisPassword = config.password;
            }

            const connectPromise = this._connectRedisContext(context);
            connectPromise.catch(() => undefined);
        }

        _log.success(`Added namespace: '${config.name}'`, MODULE_NAME);
        return this._createNamespaceHandle(config.name);
    }

    /**
     * @function getNamespace
     * @memberof mcode.cache
     * @desc Returns an immutable handle for an existing cache namespace.
     * @param {string} name the registered namespace name.
     * @returns {object} the immutable namespace handle.
     * @throws {Error} when the namespace is not registered.
     * @api public
     */
    getNamespace(name)
    {
        this._validateNamespaceName(name);
        if (!this._getNamespaceInfo(name))
        {
            throw this._cacheError('CACHE_NAMESPACE_NOT_FOUND', `Namespace '${name}' is not registered.`);
        }

        return this._createNamespaceHandle(name);
    }

    /**
     * @function probeNamespace
     * @memberof mcode.cache
     * @desc Performs a bounded Redis readiness and capability probe without registering a namespace.
     * @param {object} config explicit Redis namespace configuration.
     * @returns {object} probe status and server version.
     * @api public
     */
    async probeNamespace(config)
    {
        const normalized = this._normalizeNamespaceConfig(config);
        if (normalized.type !== 'redis')
        {
            throw this._cacheError('CACHE_REDIS_REQUIRED', 'probeNamespace requires type redis.');
        }

        const client = normalized.clientFactory(this._buildRedisClientOptions(normalized));
        client.on('error', () => undefined);
        try
        {
            await this._withTimeout(client.connect(), normalized.readyTimeoutMs, 'Redis probe connection');
            await this._withTimeout(this._verifyRedisCapabilities(client, normalized),
                normalized.readyTimeoutMs, 'Redis probe capability check');
            const info = await client.info('server');
            const version = info.match(/^redis_version:([^\r\n]+)$/m)?.[1];
            return {ok: true, version};
        }
        finally
        {
            await this._closeRedisClient(client, normalized.commandTimeoutMs);
        }
    }

    /**
     * @property {object} redisStatus the frozen stable Redis namespace status constants.
     */
    get redisStatus()
    {
        return cache.REDIS_STATUS;
    }

    /**
     * @property {string} redisMinimumVersion the minimum supported Redis server version.
     */
    get redisMinimumVersion()
    {
        return cache.REDIS_MIN_VERSION;
    }

    /**
     * @property {object} cacheErrors the frozen stable package error codes for operational branching.
     */
    get cacheErrors()
    {
        return cache.ERROR_CODES;
    }

    /**
     * @function cacheMakeKey
     * @memberof mcode.cache
     * @desc Converts a 'key source' into a cache Key by replacing slashes with colons and removing spaces.
     * @param {string} keySource the path to the key to be converted.
     * @returns {string} the cache Key.
     * @api public
     * @example
     *     const keyPath = 'components/app/tool/tool.template.htmx';
     *     returns 'GM-GPS-eMITS-UI:components:app:tool:tool.template.htmx';
     */
    cacheMakeKey(keySource)
    {
        // convert the file path into a cache Key
        let key = keySource.replace(/[\\/]/g, ':'); // Handle both forward and backward slashes

        // remove spaces ' '
        key = key.replace(/\s/g, ' ');

        // remove double-dots '..'
        key = key.replace(/\.\./g, '.');

        // remove leading '.' and trailing '.'
        key = key.replace(/^\.+|\.+$/g, '');

        // remove leading and trailing colons
        key = key.replace(/^:+|:+$/g, '');

        // now, make it specific to the caller's namespace..
        return `${this.cacheNamespace}:${key}`;
    }

    /**
     * @function cacheGet
     * @memberof mcode.cache
     * @desc Caches the results of a callback function in cache under the current namespace and returns the key's value.
     * @param {string} key the app key to get from the current namespace.
     * @param {function} cb the callback function to get fresh value.
     * @returns {Promise} the cached value.
     */
    async cacheGet(key, cb = () => {return undefined;})
    {
        // make the auto-generated cache key for the 'key' - get from current namespace, add if not cached
        const cacheKey = this.fileMakeKey(key);

        // get the namespace info for the current namespace
        const namespaceInfo = this._getNamespaceInfo(this.#cacheNamespace);
        if (!namespaceInfo)
        {
            _log.warn(`Current namespace '${this.#cacheNamespace}' not found`, MODULE_NAME);
            return cb();
        }

        // get the value from the cache associated with the current namespace
        if (namespaceInfo.type === 'redis')
        {
            return await this._redisGet(cacheKey, cb);
        }

        return await this._cacheGet(cacheKey, cb);
    }

    /**
     * @function cacheSet
     * @memberof mcode.cache
     * @desc Sets a key value in the cache.
     * @param {string} key the app key to be set into current namespace.
     * @param {string} value the value to be set in the cache.
     * @returns {string} the value set in the cache.
     */
    async cacheSet(key, value)
    {
        // make the auto-generated cache key for the 'key' - set into current namespace
        const cacheKey = this.fileMakeKey(key);

        // get the namespace info for the current namespace
        const namespaceInfo = this._getNamespaceInfo(this.#cacheNamespace);
        if (!namespaceInfo)
        {
            _log.warn(`Current namespace '${this.#cacheNamespace}' not found`, MODULE_NAME);
            return;
        }

        // set the value in the cache associated with the current namespace
        if (namespaceInfo.type === 'redis')
        {
            return await this._redisSet(cacheKey, value);
        }

        return await this._cacheSet(cacheKey, value);
    }

    /**
     * @function cacheDrop
     * @memberof mcode.cache
     * @desc Drops a key value from the cache based on the 'key' name.
     * @param {string} key the app key to be droppped.
     * @returns {number} the number of keys deleted from the cache.
     * @api public
     * @example
     *     const count = await mcode.cacheDrop(keyName);
     */
    async cacheDrop(key)
    {
        // make the auto-generated cache key for the 'key' - drop from current namespace
        const cacheKey = this.fileMakeKey(key);

        // get the namespace info for the current namespace
        const namespaceInfo = this._getNamespaceInfo(this.#cacheNamespace);
        if (!namespaceInfo)
        {
            _log.warn(`Current namespace '${this.#cacheNamespace}' not found`, MODULE_NAME);
            return 0;
        }

        // delete the value from the cache associated with the current namespace
        if (namespaceInfo.type === 'redis')
        {
            // use the Redis client
            return await this._redisDrop(cacheKey);
        }

        return await this._cacheDrop(cacheKey);
    }

    /**
     * @function cacheDropAll
     * @memberof mcode.cache
     * @desc Drops all keys from the cache based on the App's namespace.
     * @param {string} cache the cache to drop all keys from.
     * @param {string} namespace the namespace to drop all keys from.
     * @param {string} pattern the key pattern to drop all keys from.
     * @returns {number} the number of keys deleted from the cache.
     * @api public
     * @example
     *    const result = await mcode.cacheDropAll();
     *    const result = await mcode.cacheDropAll({cache: 'redis', namespace: 'GM-GPS-eMITS-DB', pattern: '*'});
     */
    async cacheDropAll({cache = '*', namespace = '*', pattern = '*'} = {})
    {
        let result = 0;

        for (const namespaceInfo of this.#cacheNamespaces)
        {
            if (namespaceInfo.name === namespace || namespace === '*')
            {
                if (namespaceInfo.type === 'node' && (cache === 'node' || cache === '*'))
                {
                    // Get keys from the Node cache
                    const nodeKeys = await this._cacheKeys(`${namespaceInfo.name}:${pattern}`);
                    result += nodeKeys.length;

                    // Delete all keys from the Node cache
                    await Promise.all(nodeKeys.map(key => this.#cache.del(key)));
                }

                if (namespaceInfo.type === 'redis' && (cache === 'redis' || cache === '*'))
                {
                    const redisKeys = await this._legacyRedisScanKeys(namespaceInfo.name, pattern, 10000);
                    result += redisKeys.length;

                    if (redisKeys.length > 0)
                    {
                        const context = this.#redisContexts.get(namespaceInfo.name);
                        await this._executeRedis(namespaceInfo.name, 'DEL',
                            client => client.del(redisKeys), true, context.config.commandTimeoutMs);
                    }
                }
            }
        }

        // Return the total number of keys deleted
        return result;
    }

    /**
     * @function cacheListAll
     * @memberof mcode.cache
     * @desc Lists all keys from the cache based on the App's namespace.
     * Includes timeout protection to prevent hanging on non-responsive caches (especially Redis).
     * Provides graceful degradation - continues processing other namespaces if one fails.
     * @param {string} cache the cache to list all keys from.
     * @param {string} namespace the namespace to list all keys from.
     * @param {string} pattern the key pattern to list all keys from.
     * @param {boolean} includeErrors whether to include error information in the response.
     * @returns {Array|Object} returns an array of keys, or an object with keys and errors if includeErrors=true.
     * @api public
     * @example
     *    const result = await mcode.cacheListAll();
     *    const result = await mcode.cacheListAll({cache: 'node', namespace: '*', pattern: '*'});
     *    const {keys, errors} = await mcode.cacheListAll({includeErrors: true});
     */
    async cacheListAll({cache = '*', namespace = '*', pattern = '*', includeErrors = false} = {})
    {
        let keys = [];
        let errors = [];
        let processedNamespaces = 0;
        let failedNamespaces = 0;

        _log.info(`Starting cacheListAll for cache: ${cache}, namespace: ${namespace}, pattern: ${pattern}`, MODULE_NAME);

        for (const namespaceInfo of this.#cacheNamespaces)
        {
            if (namespaceInfo.name === namespace || namespace === '*')
            {
                if (namespaceInfo.type === cache || cache === '*')
                {
                    processedNamespaces++;
                    _log.debug(`Processing namespace: ${namespaceInfo.name} (${namespaceInfo.type})`, MODULE_NAME);

                    try
                    {
                        let cacheKeys = [];
                        const startTime = Date.now();

                        // Get keys from the appropriate cache type with timeout protection
                        if (namespaceInfo.type === 'node')
                        {
                            // use the Node cache - NOTE: node-cache.keys() does not support wildcards
                            cacheKeys = await this._cacheKeys(`${namespaceInfo.name}:${pattern}`);
                        }
                        else if (namespaceInfo.type === 'redis')
                        {
                            // Check if Redis is connected before attempting operation
                            if (!this.#redisConnected)
                            {
                                throw new Error('Redis not connected');
                            }

                            cacheKeys = await this._legacyRedisScanKeys(namespaceInfo.name, pattern, 1000);
                        }

                        const keysTime = Date.now() - startTime;
                        _log.debug(`Retrieved ${cacheKeys.length} keys from ${namespaceInfo.name} in ${keysTime}ms`, MODULE_NAME);

                        // Process the keys using common logic with timeout protection
                        const listKeysPromise = this._listKeys(cacheKeys, namespaceInfo.name, namespaceInfo.type);
                        const keyList = await this._withTimeout(listKeysPromise, 10000, `Cache list processing for ${namespaceInfo.name}`);

                        keys = keys.concat(keyList);

                        const totalTime = Date.now() - startTime;
                        _log.debug(`Successfully processed ${keyList.length} keys from namespace ${namespaceInfo.name} in ${totalTime}ms`, MODULE_NAME);
                    }
                    catch (exp)
                    {
                        failedNamespaces++;
                        const errorInfo = {
                            namespace: namespaceInfo.name,
                            type: namespaceInfo.type,
                            error: exp.message,
                            timestamp: new Date().toISOString()
                        };

                        errors.push(errorInfo);
                        _log.warn(`Failed to get keys for namespace '${namespaceInfo.name}' (${namespaceInfo.type}): ${exp.message}`, MODULE_NAME);

                        // Add a placeholder entry to indicate this namespace had issues
                        if (includeErrors)
                        {
                            keys.push({
                                namespace: namespaceInfo.name,
                                key: '<ERROR>',
                                cache: namespaceInfo.type,
                                type: 'error',
                                preview: `Failed to retrieve keys: ${exp.message}`,
                                error: true,
                                errorDetails: errorInfo
                            });
                        }

                        // Continue with other namespaces instead of failing completely
                    }
                }
            }
        }

        const summary = `Processed ${processedNamespaces} namespaces, ${failedNamespaces} failed, returned ${keys.length} keys`;
        _log.info(`cacheListAll completed: ${summary}`, MODULE_NAME);

        // Return keys with optional error information
        if (includeErrors)
        {
            return {
                keys: keys,
                errors: errors,
                summary: {
                    totalNamespaces: processedNamespaces,
                    failedNamespaces: failedNamespaces,
                    successfulNamespaces: processedNamespaces - failedNamespaces,
                    totalKeys: keys.filter(k => !k.error).length,
                    errorKeys: keys.filter(k => k.error).length
                }
            };
        }

        return keys;
    }

    /**
     * @function cacheOn
     * @memberof mcode.cache
     * @desc Turns ON caching for a specific namespace.
     * @param {string} cacheName the name of the cache namespace to enable.
     * @returns {boolean} true if the namespace was found and enabled, false otherwise.
     * @api public
     */
    async cacheOn(cacheName)
    {
        const namespace = this.#cacheNamespaces.find(ns => ns.name === cacheName);
        if (namespace)
        {
            namespace.enabled = true;
            _log.success(`Enabled caching for namespace: ${cacheName}`, MODULE_NAME);
            return true;
        }
        else
        {
            _log.warn(`Namespace '${cacheName}' not found`, MODULE_NAME);
            return false;
        }
    }

    /**
     * @function cacheOff
     * @memberof mcode.cache
     * @desc Turns OFF caching for a specific namespace.
     * @param {string} cacheName the name of the cache namespace to disable.
     * @returns {boolean} true if the namespace was found and disabled, false otherwise.
     * @api public
     */
    async cacheOff(cacheName)
    {
        const namespace = this.#cacheNamespaces.find(ns => ns.name === cacheName);
        if (namespace)
        {
            // Drop all keys from this specific namespace
            await this.cacheDropAll({cache: namespace.type, namespace: cacheName, pattern: '*'});
            namespace.enabled = false;
            _log.success(`Disabled caching for namespace: ${cacheName}`, MODULE_NAME);
            return true;
        }
        else
        {
            _log.warn(`Namespace '${cacheName}' not found`, MODULE_NAME);
            return false;
        }
    }

    /**
     * @function cacheEnabled
     * @memberof mcode.cache
     * @desc Checks if caching is enabled for a specific namespace.
     * @param {string} cacheName the name of the cache namespace to check.
     * @returns {boolean} true if caching is enabled for the namespace, false otherwise.
     * @api public
     * @example
     *   const isEnabled = mcode.cacheEnabled('MicroCODE');
     */
    cacheEnabled(cacheName)
    {
        const namespace = this.#cacheNamespaces.find(ns => ns.name === cacheName);
        if (namespace)
        {
            return namespace.enabled;
        }
        else
        {
            _log.warn(`Namespace '${cacheName}' not found`, MODULE_NAME);
            return false;
        }
    }

    /**
     * @function refreshCacheStatistics
     * @memberof mcode.cache
     * @desc Refreshes cache statistics for all Redis namespaces (async operation).
     * @returns {Promise} Promise that resolves when statistics are updated.
     * @api public
     * @example
     *   await mcode.refreshCacheStatistics();
     */
    async refreshCacheStatistics()
    {
        for (const namespace of this.#cacheNamespaces)
        {
            if (namespace.type === 'redis')
            {
                try
                {
                    const namespaceKeys = await this._legacyRedisScanKeys(namespace.name, '*', 10000);
                    namespace.keys = namespaceKeys.length;
                    const ksize = namespaceKeys.reduce((size, key) =>
                        size + Buffer.byteLength(key, 'utf8'), 0);
                    let vsize = 0;
                    for (let index = 0; index < namespaceKeys.length; index += 100)
                    {
                        const batch = namespaceKeys.slice(index, index + 100);
                        const sizes = await this._executeRedis(namespace.name, 'MEMORY USAGE',
                            client => Promise.all(batch.map(key => client.memoryUsage(key))));
                        vsize += sizes.reduce((size, value) => size + (value || 0), 0);
                    }
                    namespace.ksize = ksize;
                    namespace.vsize = vsize;
                }
                catch (error)
                {
                    _log.warn(`Could not refresh statistics for Redis namespace '${namespace.name}'`, MODULE_NAME);
                }
            }
        }
    }

    /**
     * @function closeNamespace
     * @memberof mcode.cache
     * @desc Closes all namespace-owned cache resources.
     * @returns {Promise<void>} resolves after all namespace resources close.
     * @api public
     * @example
     *   await mcode.closeNamespace();
     */
    async closeNamespace()
    {
        await Promise.allSettled(Array.from(this.#redisContexts.keys())
            .map(name => this._closeRedisNamespace(name)));

        if (this.#cache)
        {
            this.#cache.close();
            this.#cache = null;
        }
        this.#redis = null;
        this.#redisConnected = false;
    }

    /**
     * @function fileRead
     * @memberof mcode.cache
     * @desc Reads a file from 'path' and caches its for future reference. The cache 'key' generated
     * is based on the 'path' and the server's base URL (which is removed from the 'key' before caching).
     * @api public
     * @param {string} filePath a standard file system reference to the file to be read,
     * @param {string} fileEncoding the encoding of the file to be read (default is 'utf8').
     *
     * NOTE: 'filePath' is reduced to the unique sub-folder path to the file being read on the server.
     *       Explicit paths to files outside the server's root directory are supported with
     *       the 'complete path' parameter becoming the unique key for the file.
     *
     * @returns {string} the contents of the file read from 'path'.
     *
     * @example
     *      const filePath = './data.json';
     *      const fileData = mcode.fileRead(path.join(__dirname, filePath);
     *
     *      filePath: "D:\MicroCODE\GM-GPS-eMITS-UI\Source\backend\components\app\tool\tool.template.htmx",
     *      rootDir: "D:\MicroCODE\GM-GPS-eMITS-UI\Source\backend",
     *      keyPath: "\components\app\tool\tool.template.htmx",
     *      key: "GM-GPS-eMITS-UI:components:app:tool:tool.template.htmx"
     *
     * The 1st time 'mcode.fileRead()' is called, the file is read from disk and cached.
     * The 2nd time 'mcode.fileRead()' is called, the file is read from the cache.
     * The 'key' used to cache the file is based on the 'path' and the server's base URL
     * and does not need to be provided by the caller, nor stored by the caller, it is transparent.
     *
     */
    async fileRead(filePath, fileEncoding = 'utf8')
    {
        try
        {
            // make the auto-generated cache key for the file
            const cacheKey = this.fileMakeKey(filePath);

            return this._cacheGet(cacheKey, async () =>
            {
                try
                {
                    // Check if the file exists and is accessible
                    await fs.access(filePath, fs.constants.R_OK);
                }
                catch (exp)
                {
                    _log.exp(`File is NOT READ accessible: ${filePath}`, MODULE_NAME, exp);
                    throw new Error(`File READ access error: ${filePath}`);
                }

                return await fs.readFile(filePath, fileEncoding);
            });
        }
        catch (exp)
        {
            _log.exp(`Exception reading from disk for cache, file: ${filePath}`, MODULE_NAME, exp);
            return null;
        }
    }

    /**
     * @function fileWrite
     * @memberof mcode.cache
     * @desc Writes 'fileData' to 'filePath' and caches it in the cache.
     * @param {string} filePath a standard file system reference to the file to be read.
     * @param {string} fileData the data to be written to the file.
     * @param {string} fileEncoding the encoding of the file to be written (default is 'utf8').
     * @returns {Promise} the file data written to disk.
     */
    async fileWrite(filePath, fileData, fileEncoding = 'utf8')
    {
        try
        {
            // make the auto-generated cache key for the file
            const cacheKey = this.fileMakeKey(filePath);

            // the cached value is no longer valid, so drop it
            this.cacheDrop(cacheKey);

            // cache the new value
            this._cacheSet(cacheKey, fileData);

            try
            {
                // Check if the file exists and is accessible
                await fs.access(filePath, fs.constants.W_OK);
            }
            catch (exp)
            {
                _log.exp(`File is NOT WRITE accessible: ${filePath}`, MODULE_NAME, exp);
                throw new Error(`File WRITE access error: ${filePath}`);
            }

            // write the file to disk
            return await fs.writeFile(filePath, fileData, {encoding: fileEncoding});
        }
        catch (exp)
        {
            _log.exp(`Exception writing to disk and cache, file: ${filePath}`, MODULE_NAME, exp);
            return null;
        }
    }

    /**
     * @function fileDrop
     * @memberof mcode.cache
     * @desc Drops a file from the cache based on the 'filePath'.
     * @param {string} filePath a standard file system reference to the file to be read.
     * @returns {number} the number of keys deleted from the cache.
     * @api public
     * @example
     *     const filePath = './data.json';
     *     const result = await mcode.fileDrop(path.join(__dirname, filePath));
     */
    async fileDrop(filePath)
    {
        const cacheKey = this.fileMakeKey(filePath);

        return await this._cacheDrop(cacheKey);
    }

    /**
     * @function fileMakeKey
     * @memberof mcode.cache
     * @desc Generates a unique key for the file in the cache based on the 'filePath'.
     * @param {string} filePath a standard file system reference to the file to be read.
     * @returns {string} the key for the file in the cache.
     */
    fileMakeKey(filePath)
    {
        // remove 'rootKey' from the 'filePath'
        const keyPath = filePath.replace(this.fileGetRoot(), '');
        const key = this.cacheMakeKey(keyPath);

        return key;
    }

    /**
     * @function fileGetRoot
     * @memberof mcode.cache
     * @desc Gets the root directory for cache Keys based on the server's execution path.
     * @returns {string} the root directory for the server.
     * @api public
     * @example
     *    const rootDir = mcode.fileGetRoot();
     */
    fileGetRoot()
    {
        // get the execution root directory
        const mainDir = path.dirname(require.main.filename);

        // Determine the common base path
        const rootDir = path.resolve(path.join(mainDir, '..'));

        return rootDir;
    }

    // #endregion

    // #region  M E T H O D S – P R I V A T E

    /**
     * @function _getNamespaceInfo
     * @api private
     * @memberof mcode.cache
     * @desc Gets namespace information by name.
     * @param {string} namespaceName the name of the namespace to find.
     * @returns {object|null} the namespace object or null if not found.
     */
    _getNamespaceInfo(namespaceName)
    {
        return this.#cacheNamespaces.find(ns => ns.name === namespaceName) || null;
    }

    // #region  S C O P E D   C O N T R A C T   A N D   C O D E C

    /**
     * @function _cacheError
     * @memberof mcode.cache
     * @desc Creates an Error with a stable package error code and optional cause.
     * @param {string} code the stable package error code.
     * @param {string} message the human-readable error message.
     * @param {Error} cause the optional underlying error.
     * @returns {Error} the coded cache error.
     * @api private
     */
    _cacheError(code, message, cause)
    {
        const error = new Error(message, cause ? {cause} : undefined);
        error.code = code;
        return error;
    }

    /**
     * @function _validateNamespaceName
     * @memberof mcode.cache
     * @desc Validates a namespace name against the scoped cache contract.
     * @param {string} name the namespace name to validate.
     * @returns {string} the validated namespace name.
     * @api private
     */
    _validateNamespaceName(name)
    {
        if (typeof name !== 'string' || !name ||
            Buffer.byteLength(name, 'utf8') > cache.MAX_NAMESPACE_BYTES ||
            !/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(name))
        {
            throw this._cacheError('CACHE_INVALID_NAMESPACE',
                'Namespace names must be 1-64 bytes and contain only letters, digits, dot, underscore, or hyphen.');
        }

        return name;
    }

    /**
     * @function _validateLogicalName
     * @memberof mcode.cache
     * @desc Validates a logical key or channel without a namespace prefix.
     * @param {string} value the logical name to validate.
     * @param {string} kind the logical-name kind, either key or channel.
     * @returns {string} the validated logical name.
     * @api private
     */
    _validateLogicalName(value, kind = 'key')
    {
        const maximum = kind === 'channel' ? cache.MAX_CHANNEL_BYTES : cache.MAX_LOGICAL_KEY_BYTES;
        if (typeof value !== 'string' || !value || Buffer.byteLength(value, 'utf8') > maximum)
        {
            throw this._cacheError(`CACHE_INVALID_${kind.toUpperCase()}`,
                `Logical ${kind} must be a non-empty string no larger than ${maximum} bytes.`);
        }

        const segments = value.split(':');
        if (segments.some(segment => !/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(segment)))
        {
            throw this._cacheError(`CACHE_INVALID_${kind.toUpperCase()}`,
                `Logical ${kind} segments may contain only letters, digits, dot, underscore, or hyphen.`);
        }

        return value;
    }

    /**
     * @function _physicalKey
     * @memberof mcode.cache
     * @desc Builds a namespace-owned Redis key from a validated logical key.
     * @param {string} namespaceName the namespace that owns the key.
     * @param {string} logicalKey the unprefixed logical key.
     * @returns {string} the physical Redis key.
     * @api private
     */
    _physicalKey(namespaceName, logicalKey)
    {
        this._validateLogicalName(logicalKey);
        if (logicalKey === namespaceName || logicalKey.startsWith(`${namespaceName}:`))
        {
            throw this._cacheError('CACHE_ALREADY_PREFIXED',
                `Logical key '${logicalKey}' must not include namespace '${namespaceName}'.`);
        }

        return `${namespaceName}:${logicalKey}`;
    }

    /**
     * @function _physicalChannel
     * @memberof mcode.cache
     * @desc Builds a namespace-owned Redis channel from a validated logical channel.
     * @param {string} namespaceName the namespace that owns the channel.
     * @param {string} logicalChannel the unprefixed logical channel.
     * @returns {string} the physical Redis channel.
     * @api private
     */
    _physicalChannel(namespaceName, logicalChannel)
    {
        this._validateLogicalName(logicalChannel, 'channel');
        if (logicalChannel === namespaceName || logicalChannel.startsWith(`${namespaceName}:`))
        {
            throw this._cacheError('CACHE_ALREADY_PREFIXED',
                `Logical channel '${logicalChannel}' must not include namespace '${namespaceName}'.`);
        }

        return `${namespaceName}:${logicalChannel}`;
    }

    /**
     * @function _normalizeNamespaceConfig
     * @memberof mcode.cache
     * @desc Validates and freezes an explicit node or Redis namespace configuration.
     * @param {object} namespace the namespace configuration to normalize.
     * @returns {object} the normalized namespace configuration.
     * @api private
     */
    _normalizeNamespaceConfig(namespace)
    {
        if (!namespace || typeof namespace !== 'object')
        {
            throw this._cacheError('CACHE_INVALID_NAMESPACE', 'Namespace configuration must be an object.');
        }

        const name = this._validateNamespaceName(namespace.name);
        if (namespace.type !== 'node' && namespace.type !== 'redis')
        {
            throw this._cacheError('CACHE_INVALID_TYPE', `Namespace '${name}' type must be 'node' or 'redis'.`);
        }

        if (namespace.type === 'node')
        {
            return {name, type: 'node'};
        }

        const required = [
            'url',
            'username',
            'password',
            'retry',
            'readyTimeoutMs',
            'commandTimeoutMs',
            'disableOfflineQueue'
        ];
        const missing = required.filter(property => !Object.prototype.hasOwnProperty.call(namespace, property));
        if (missing.length > 0)
        {
            throw this._cacheError('CACHE_CONFIG_REQUIRED',
                `Redis namespace '${name}' is missing explicit configuration: ${missing.join(', ')}.`);
        }

        let parsedURL;
        try
        {
            parsedURL = new URL(namespace.url);
        }
        catch (error)
        {
            throw this._cacheError('CACHE_INVALID_CONFIG', `Redis namespace '${name}' has an invalid URL.`, error);
        }

        if (parsedURL.protocol !== 'redis:' && parsedURL.protocol !== 'rediss:')
        {
            throw this._cacheError('CACHE_INVALID_CONFIG', 'Redis URL protocol must be redis: or rediss:.');
        }

        if (namespace.username !== null && typeof namespace.username !== 'string')
        {
            throw this._cacheError('CACHE_INVALID_CONFIG', 'Redis username must be a string or null.');
        }
        if (namespace.password !== null && typeof namespace.password !== 'string')
        {
            throw this._cacheError('CACHE_INVALID_CONFIG', 'Redis password must be a string or null.');
        }
        if (typeof namespace.disableOfflineQueue !== 'boolean')
        {
            throw this._cacheError('CACHE_INVALID_CONFIG', 'disableOfflineQueue must be an explicit boolean.');
        }

        this._validatePositiveInteger(namespace.readyTimeoutMs, 'readyTimeoutMs');
        this._validatePositiveInteger(namespace.commandTimeoutMs, 'commandTimeoutMs');
        if (!namespace.retry || typeof namespace.retry !== 'object')
        {
            throw this._cacheError('CACHE_INVALID_CONFIG', 'retry must be an explicit configuration object.');
        }
        this._validatePositiveInteger(namespace.retry.baseDelayMs, 'retry.baseDelayMs');
        this._validatePositiveInteger(namespace.retry.maxDelayMs, 'retry.maxDelayMs');
        this._validatePositiveInteger(namespace.retry.maxAttempts, 'retry.maxAttempts');
        if (namespace.retry.baseDelayMs > namespace.retry.maxDelayMs)
        {
            throw this._cacheError('CACHE_INVALID_CONFIG',
                'retry.baseDelayMs must not exceed retry.maxDelayMs.');
        }
        if (namespace.clientFactory !== undefined && typeof namespace.clientFactory !== 'function')
        {
            throw this._cacheError('CACHE_INVALID_CONFIG', 'clientFactory must be a function when provided.');
        }

        return Object.freeze({
            name,
            type: 'redis',
            url: namespace.url,
            username: namespace.username,
            password: namespace.password,
            retry: Object.freeze({...namespace.retry}),
            readyTimeoutMs: namespace.readyTimeoutMs,
            commandTimeoutMs: namespace.commandTimeoutMs,
            disableOfflineQueue: namespace.disableOfflineQueue,
            clientFactory: namespace.clientFactory || Redis.createClient
        });
    }

    /**
     * @function _validatePositiveInteger
     * @memberof mcode.cache
     * @desc Requires a configuration value to be a positive safe integer.
     * @param {number} value the numeric value to validate.
     * @param {string} name the configuration field name.
     * @returns {void}
     * @api private
     */
    _validatePositiveInteger(value, name)
    {
        if (!Number.isSafeInteger(value) || value <= 0)
        {
            throw this._cacheError('CACHE_INVALID_CONFIG', `${name} must be a positive integer.`);
        }
    }

    /**
     * @function _validateOptionsObject
     * @memberof mcode.cache
     * @desc Requires an operation's options value to be a non-array object.
     * @param {object} options the options value to validate.
     * @param {string} operation the operation name used in errors.
     * @returns {object} the validated options object.
     * @api private
     */
    _validateOptionsObject(options, operation)
    {
        if (!options || typeof options !== 'object' || Array.isArray(options))
        {
            throw this._cacheError('CACHE_INVALID_OPTIONS', `${operation} options must be an object.`);
        }
        return options;
    }

    /**
     * @function _remainingDeadline
     * @memberof mcode.cache
     * @desc Calculates remaining bounded operation time and rejects expired work.
     * @param {number} expiresAt the absolute deadline in epoch milliseconds.
     * @param {string} operation the operation name used in errors.
     * @returns {number} the remaining deadline in milliseconds.
     * @api private
     */
    _remainingDeadline(expiresAt, operation)
    {
        const remaining = expiresAt - Date.now();
        if (remaining <= 0)
        {
            throw this._cacheError('CACHE_TIMEOUT', `${operation} deadline expired.`);
        }
        return remaining;
    }

    /**
     * @function _redisConfigSignature
     * @memberof mcode.cache
     * @desc Creates the stable comparison signature for Redis namespace idempotence.
     * @param {object} config the normalized Redis namespace configuration.
     * @returns {string} the serialized non-function configuration signature.
     * @api private
     */
    _redisConfigSignature(config)
    {
        return JSON.stringify({
            url: config.url,
            username: config.username,
            password: config.password,
            retry: config.retry,
            readyTimeoutMs: config.readyTimeoutMs,
            commandTimeoutMs: config.commandTimeoutMs,
            disableOfflineQueue: config.disableOfflineQueue
        });
    }

    /**
     * @function _createNamespaceHandle
     * @memberof mcode.cache
     * @desc Creates or returns the immutable scoped handle for a namespace.
     * @param {string} name the registered namespace name.
     * @returns {object} the immutable namespace handle.
     * @api private
     */
    _createNamespaceHandle(name)
    {
        if (this.#namespaceHandles.has(name))
        {
            return this.#namespaceHandles.get(name);
        }

        const namespace = this._getNamespaceInfo(name);
        const owner = this;
        const handle = {
            name,
            type: namespace.type,
            get enabled()
            {
                return owner._getNamespaceInfo(name)?.enabled === true;
            },
            get status()
            {
                if (namespace.type === 'node')
                {
                    return owner.#cache ? cache.REDIS_STATUS.CONNECTED : cache.REDIS_STATUS.DISCONNECTED;
                }
                return owner.#redisContexts.get(name)?.status || cache.REDIS_STATUS.NOT_CONFIGURED;
            },
            ready: options => owner._namespaceReady(name, options),
            cacheGet: key => owner._namespaceCacheGet(name, key),
            cacheGetMany: keys => owner._namespaceCacheGetMany(name, keys),
            cacheSet: (key, value, options) => owner._namespaceCacheSet(name, key, value, options),
            cacheDrop: keyOrKeys => owner._namespaceCacheDrop(name, keyOrKeys),
            cacheDropIfEqual: (key, expectedValue) => owner._namespaceCacheDropIfEqual(name, key, expectedValue),
            cacheExists: key => owner._namespaceCacheExists(name, key),
            cacheTTL: key => owner._namespaceCacheTTL(name, key, false),
            cachePTTL: key => owner._namespaceCacheTTL(name, key, true),
            cacheExpire: (key, options) => owner._namespaceCacheExpire(name, key, options),
            ping: () => owner._namespacePing(name),
            info: section => owner._namespaceInfo(name, section),
            time: () => owner._namespaceTime(name),
            scan: options => owner._namespaceScan(name, options),
            inspect: options => owner._namespaceInspect(name, options),
            geoAdd: (key, members) => owner._namespaceGeoAdd(name, key, members),
            geoRemove: (key, members) => owner._namespaceGeoRemove(name, key, members),
            geoSearch: (key, options) => owner._namespaceGeoSearch(name, key, options),
            sortedSetAdd: (key, members, options) => owner._namespaceSortedSetAdd(name, key, members, options),
            sortedSetRemove: (key, members) => owner._namespaceSortedSetRemove(name, key, members),
            sortedSetRange: (key, options) => owner._namespaceSortedSetRange(name, key, options),
            sortedSetRangeByScore: (key, options) => owner._namespaceSortedSetRangeByScore(name, key, options),
            sortedSetRank: (key, member, reverse) => owner._namespaceSortedSetRank(name, key, member, reverse),
            sortedSetScore: (key, member) => owner._namespaceSortedSetScore(name, key, member),
            multi: () => owner._createMultiBuilder(name),
            watchTransaction: (options, planner) => owner._watchTransaction(name, options, planner),
            ensureGeneration: options => owner._ensureGeneration(name, options),
            resetGeneration: options => owner._resetGeneration(name, options),
            publish: (channel, value) => owner._namespacePublish(name, channel, value),
            createSubscriber: options => owner._createSubscriber(name, options),
            close: () => owner._closeRedisNamespace(name)
        };

        Object.freeze(handle);
        this.#namespaceHandles.set(name, handle);
        return handle;
    }

    /**
     * @function _canonicalize
     * @memberof mcode.cache
     * @desc Recursively validates and key-sorts a supported typed cache value.
     * @param {*} value the value to canonicalize.
     * @param {Set} seen the object references in the current recursion path.
     * @returns {*} the canonical JSON-compatible value.
     * @api private
     */
    _canonicalize(value, seen = new Set())
    {
        if (value === null || typeof value === 'string' || typeof value === 'boolean')
        {
            return value;
        }
        if (typeof value === 'number')
        {
            if (!Number.isFinite(value))
            {
                throw this._cacheError('CACHE_VALUE_UNSUPPORTED', 'Cache numbers must be finite.');
            }
            return value;
        }
        if (typeof value !== 'object' || Buffer.isBuffer(value) || value instanceof Date)
        {
            throw this._cacheError('CACHE_VALUE_UNSUPPORTED',
                'Cache values support null, booleans, finite numbers, strings, arrays, and plain objects.');
        }
        if (seen.has(value))
        {
            throw this._cacheError('CACHE_VALUE_UNSUPPORTED', 'Cache values must not contain circular references.');
        }

        seen.add(value);
        let result;
        if (Array.isArray(value))
        {
            result = value.map(item =>
            {
                if (item === undefined)
                {
                    throw this._cacheError('CACHE_VALUE_UNSUPPORTED', 'Undefined array values are not supported.');
                }
                return this._canonicalize(item, seen);
            });
        }
        else
        {
            const prototype = Object.getPrototypeOf(value);
            if (prototype !== Object.prototype && prototype !== null)
            {
                throw this._cacheError('CACHE_VALUE_UNSUPPORTED', 'Only plain object cache values are supported.');
            }
            result = {};
            for (const key of Object.keys(value).sort())
            {
                if (value[key] === undefined)
                {
                    throw this._cacheError('CACHE_VALUE_UNSUPPORTED', 'Undefined object values are not supported.');
                }
                result[key] = this._canonicalize(value[key], seen);
            }
        }
        seen.delete(value);
        return result;
    }

    /**
     * @function _encodeValue
     * @memberof mcode.cache
     * @desc Encodes a supported value with the versioned canonical cache codec.
     * @param {*} value the value to encode.
     * @returns {string} the versioned encoded Redis value.
     * @api private
     */
    _encodeValue(value)
    {
        if (value === undefined)
        {
            throw this._cacheError('CACHE_VALUE_UNSUPPORTED', 'Undefined is reserved for a missing cache value.');
        }

        const encoded = `${cache.REDIS_VALUE_PREFIX}${JSON.stringify(this._canonicalize(value))}`;
        if (Buffer.byteLength(encoded, 'utf8') > cache.MAX_VALUE_BYTES)
        {
            throw this._cacheError('CACHE_VALUE_TOO_LARGE',
                `Encoded cache values must not exceed ${cache.MAX_VALUE_BYTES} bytes.`);
        }
        return encoded;
    }

    /**
     * @function _decodeValue
     * @memberof mcode.cache
     * @desc Decodes a versioned cache value while preserving missing-value semantics.
     * @param {string|null|undefined} value the stored Redis value.
     * @returns {*} the decoded value, or undefined when missing.
     * @api private
     */
    _decodeValue(value)
    {
        if (value === null || value === undefined)
        {
            return undefined;
        }
        if (!value.startsWith(cache.REDIS_VALUE_PREFIX))
        {
            throw this._cacheError('CACHE_VALUE_FORMAT', 'Stored value does not use the mcode-cache typed codec.');
        }

        try
        {
            return JSON.parse(value.slice(cache.REDIS_VALUE_PREFIX.length));
        }
        catch (error)
        {
            throw this._cacheError('CACHE_VALUE_FORMAT', 'Stored cache value is malformed.', error);
        }
    }

    // #endregion

    // #region  R E D I S   C O N N E C T I O N   A N D   D E A D L I N E S

    /**
     * @function _createRedisContext
     * @memberof mcode.cache
     * @desc Creates the private lifecycle state for one Redis namespace.
     * @param {object} config the normalized Redis namespace configuration.
     * @returns {object} the mutable private Redis context.
     * @api private
     */
    _createRedisContext(config)
    {
        return {
            config,
            signature: this._redisConfigSignature(config),
            status: cache.REDIS_STATUS.IDLE,
            client: null,
            connectPromise: null,
            closePromise: null,
            subscribers: new Set(),
            transactionClients: new Set(),
            lastError: null,
            outageLogged: false,
            closing: false
        };
    }

    /**
     * @function _buildRedisClientOptions
     * @memberof mcode.cache
     * @desc Maps explicit namespace policy to node-redis client options.
     * @param {object} config the normalized Redis namespace configuration.
     * @returns {object} the node-redis client options.
     * @api private
     */
    _buildRedisClientOptions(config)
    {
        return {
            url: config.url,
            username: config.username ?? undefined,
            password: config.password ?? undefined,
            disableOfflineQueue: config.disableOfflineQueue,
            socket: {
                connectTimeout: config.readyTimeoutMs,
                reconnectStrategy: retries =>
                {
                    if (retries >= config.retry.maxAttempts)
                    {
                        return new Error(`Redis reconnect attempts exceeded ${config.retry.maxAttempts}.`);
                    }
                    return Math.min(
                        config.retry.baseDelayMs * Math.pow(2, retries),
                        config.retry.maxDelayMs
                    );
                }
            }
        };
    }

    /**
     * @function _transitionRedisContext
     * @memberof mcode.cache
     * @desc Applies a deduplicated Redis lifecycle transition and outage log state.
     * @param {object} context the Redis namespace context.
     * @param {string} status the stable package status value.
     * @param {Error} error the optional transition error.
     * @returns {void}
     * @api private
     */
    _transitionRedisContext(context, status, error)
    {
        if (error)
        {
            context.lastError = error;
        }
        if (context.status === status)
        {
            return;
        }

        context.status = status;
        this.#redisConnected = Array.from(this.#redisContexts.values())
            .some(item => item.status === cache.REDIS_STATUS.CONNECTED);

        if (status === cache.REDIS_STATUS.CONNECTED)
        {
            if (context.outageLogged)
            {
                _log.success(`Redis namespace '${context.config.name}' recovered.`, MODULE_NAME);
            }
            context.lastError = null;
            context.outageLogged = false;
        }
        else if (status === cache.REDIS_STATUS.DISCONNECTED && !context.outageLogged)
        {
            context.outageLogged = true;
            _log.warn(`Redis namespace '${context.config.name}' is unavailable: ${error?.message || 'disconnected'}`,
                MODULE_NAME);
        }
    }

    /**
     * @function _attachRedisClientListeners
     * @memberof mcode.cache
     * @desc Attaches guarded lifecycle and required error listeners to a Redis client.
     * @param {object} context the Redis namespace context.
     * @param {object} client the node-redis client.
     * @returns {void}
     * @api private
     */
    _attachRedisClientListeners(context, client)
    {
        client.on('error', error =>
            this._transitionRedisContext(context, cache.REDIS_STATUS.DISCONNECTED, error));
        client.on('reconnecting', () =>
            this._transitionRedisContext(context, cache.REDIS_STATUS.CONNECTING));
        client.on('end', () =>
        {
            if (!context.closing)
            {
                this._transitionRedisContext(context, cache.REDIS_STATUS.DISCONNECTED);
            }
        });
        client.on('ready', () =>
        {
            if ((context.status === cache.REDIS_STATUS.DISCONNECTED ||
                context.status === cache.REDIS_STATUS.CONNECTING) &&
                !context.connectPromise && !context.closing)
            {
                const connectPromise = this._verifyRedisCapabilities(client, context.config)
                    .then(() => this._transitionRedisContext(context, cache.REDIS_STATUS.CONNECTED))
                    .catch(error =>
                    {
                        this._transitionRedisContext(context, cache.REDIS_STATUS.DISCONNECTED, error);
                        this._destroyRedisClient(client);
                        throw error;
                    })
                    .finally(() =>
                    {
                        if (context.connectPromise === connectPromise)
                        {
                            context.connectPromise = null;
                        }
                    });
                context.connectPromise = connectPromise;
                context.connectPromise.catch(() => undefined);
            }
        });
    }

    /**
     * @function _connectRedisContext
     * @memberof mcode.cache
     * @desc Creates, connects, and capability-gates a namespace command client.
     * @param {object} context the Redis namespace context.
     * @returns {Promise<object>} the ready node-redis client.
     * @api private
     */
    _connectRedisContext(context)
    {
        if (context.status === cache.REDIS_STATUS.CONNECTED && context.client?.isReady)
        {
            return context.client;
        }
        if (context.connectPromise)
        {
            return context.connectPromise;
        }

        const connectPromise = (async () =>
        {
            context.closing = false;
            this._transitionRedisContext(context, cache.REDIS_STATUS.CONNECTING);
            if (!context.client || !context.client.isOpen)
            {
                context.client = context.config.clientFactory(this._buildRedisClientOptions(context.config));
                this._attachRedisClientListeners(context, context.client);
            }

            try
            {
                if (!context.client.isOpen)
                {
                    await this._withTimeout(context.client.connect(), context.config.readyTimeoutMs,
                        `Redis readiness for '${context.config.name}'`);
                }
                await this._withTimeout(
                    this._verifyRedisCapabilities(context.client, context.config),
                    context.config.readyTimeoutMs,
                    `Redis capability check for '${context.config.name}'`
                );
                this._transitionRedisContext(context, cache.REDIS_STATUS.CONNECTED);
                if (this.#redisContexts.size === 1)
                {
                    this.#redis = context.client;
                }
                return context.client;
            }
            catch (error)
            {
                this._transitionRedisContext(context, cache.REDIS_STATUS.DISCONNECTED, error);
                if (context.client)
                {
                    this._destroyRedisClient(context.client);
                }
                throw error;
            }
        })().finally(() =>
        {
            if (context.connectPromise === connectPromise)
            {
                context.connectPromise = null;
            }
        });

        context.connectPromise = connectPromise;
        return connectPromise;
    }

    /**
     * @function _verifyRedisCapabilities
     * @memberof mcode.cache
     * @desc Verifies PING, Redis version, DELEX support, and standalone mode.
     * @param {object} client the connected node-redis client.
     * @param {object} config the normalized Redis namespace configuration.
     * @returns {Promise<void>}
     * @api private
     */
    async _verifyRedisCapabilities(client, config)
    {
        const pong = await client.ping();
        if (pong !== 'PONG')
        {
            throw this._cacheError('CACHE_REDIS_CAPABILITY', 'Redis PING did not return PONG.');
        }

        const serverInfo = await client.info('server');
        const versionMatch = serverInfo.match(/^redis_version:([^\r\n]+)$/m);
        const version = versionMatch?.[1];
        if (!version || this._compareVersions(version, cache.REDIS_MIN_VERSION) < 0)
        {
            throw this._cacheError('CACHE_REDIS_VERSION',
                `Redis ${cache.REDIS_MIN_VERSION} or newer is required; server reported '${version || 'unknown'}'.`);
        }

        const commandInfo = await client.sendCommand(['COMMAND', 'INFO', 'DELEX']);
        if (!Array.isArray(commandInfo) || !commandInfo[0])
        {
            throw this._cacheError('CACHE_REDIS_CAPABILITY',
                'Redis DELEX support is required for compare-and-delete.');
        }

        const clusterInfo = await client.info('cluster');
        if (/^cluster_enabled:1$/m.test(clusterInfo))
        {
            throw this._cacheError('CACHE_REDIS_MODE',
                `Redis namespace '${config.name}' requires a standalone server, not cluster mode.`);
        }
    }

    /**
     * @function _compareVersions
     * @memberof mcode.cache
     * @desc Compares the first three numeric components of two server versions.
     * @param {string} left the reported server version.
     * @param {string} right the minimum required server version.
     * @returns {number} -1, 0, or 1 for less than, equal, or greater than.
     * @api private
     */
    _compareVersions(left, right)
    {
        const leftParts = String(left).split(/[.-]/).slice(0, 3).map(part => Number.parseInt(part, 10) || 0);
        const rightParts = String(right).split(/[.-]/).slice(0, 3).map(part => Number.parseInt(part, 10) || 0);
        for (let index = 0; index < 3; index++)
        {
            if (leftParts[index] !== rightParts[index])
            {
                return leftParts[index] > rightParts[index] ? 1 : -1;
            }
        }
        return 0;
    }

    /**
     * @function _namespaceReady
     * @memberof mcode.cache
     * @desc Waits within a deadline for a namespace handle to become ready.
     * @param {string} name the registered namespace name.
     * @param {object} options the bounded readiness options.
     * @returns {Promise<object>} the immutable ready namespace handle.
     * @api private
     */
    async _namespaceReady(name, options = {})
    {
        this._validateOptionsObject(options, 'ready');
        const namespace = this._getNamespaceInfo(name);
        if (namespace.type === 'node')
        {
            return this._createNamespaceHandle(name);
        }

        const context = this.#redisContexts.get(name);
        const timeoutMs = options.timeoutMs ?? context.config.readyTimeoutMs;
        this._validatePositiveInteger(timeoutMs, 'timeoutMs');
        const expiresAt = Date.now() + timeoutMs;

        if (context.closePromise)
        {
            await this._withTimeout(context.closePromise,
                this._remainingDeadline(expiresAt, `Redis close for '${name}'`),
                `Redis close for '${name}'`);
        }

        if (context.status === cache.REDIS_STATUS.CONNECTED && context.client?.isReady)
        {
            return this._createNamespaceHandle(name);
        }

        if (context.connectPromise)
        {
            try
            {
                await this._withTimeout(context.connectPromise,
                    this._remainingDeadline(expiresAt, `Redis readiness for '${name}'`),
                    `Redis readiness for '${name}'`);
            }
            catch (error)
            {
                if (['CACHE_REDIS_VERSION', 'CACHE_REDIS_MODE', 'CACHE_REDIS_CAPABILITY']
                    .includes(error.code))
                {
                    throw error;
                }
                if (context.client?.isOpen)
                {
                    this._destroyRedisClient(context.client);
                }
                context.client = null;
                context.connectPromise = null;
                await this._withTimeout(this._connectRedisContext(context),
                    this._remainingDeadline(expiresAt, `Redis readiness for '${name}'`),
                    `Redis readiness for '${name}'`);
            }
        }
        else
        {
            if (context.client)
            {
                this._destroyRedisClient(context.client);
                context.client = null;
            }
            await this._withTimeout(this._connectRedisContext(context),
                this._remainingDeadline(expiresAt, `Redis readiness for '${name}'`),
                `Redis readiness for '${name}'`);
        }

        return this._createNamespaceHandle(name);
    }

    /**
     * @function _executeRedis
     * @memberof mcode.cache
     * @desc Executes one Redis task with readiness, deadline, and ambiguity handling.
     * @param {string} name the Redis namespace name.
     * @param {string} operation the operation name used in errors.
     * @param {function} task the function receiving the ready command client.
     * @param {boolean} mutation whether a post-dispatch timeout is outcome-unknown.
     * @param {number} timeoutMs the optional operation timeout override.
     * @returns {Promise<*>} the Redis operation result.
     * @api private
     */
    async _executeRedis(name, operation, task, mutation = false, timeoutMs)
    {
        const namespace = this._getNamespaceInfo(name);
        if (!namespace || namespace.type !== 'redis')
        {
            throw this._cacheError('CACHE_REDIS_REQUIRED', `Namespace '${name}' is not Redis-backed.`);
        }
        if (!namespace.enabled)
        {
            throw this._cacheError('CACHE_DISABLED', `Namespace '${name}' is disabled.`);
        }

        const context = this.#redisContexts.get(name);
        const timeout = timeoutMs ?? context.config.commandTimeoutMs;
        this._validatePositiveInteger(timeout, 'command timeout');
        const expiresAt = Date.now() + timeout;
        await this._namespaceReady(name, {timeoutMs: Math.min(timeout, context.config.readyTimeoutMs)});
        const remaining = expiresAt - Date.now();
        if (remaining <= 0)
        {
            throw this._cacheError('CACHE_TIMEOUT', `${operation} deadline expired before dispatch.`);
        }

        let timeoutId;
        const timeoutError = new Promise((_, reject) =>
        {
            timeoutId = setTimeout(() =>
            {
                reject(this._cacheError(
                    mutation ? 'CACHE_OUTCOME_UNKNOWN' : 'CACHE_TIMEOUT',
                    mutation ?
                        `${operation} timed out after dispatch; outcome is unknown and must be reconciled.` :
                        `${operation} timed out after ${timeout}ms.`
                ));
            }, remaining);
        });

        try
        {
            return await Promise.race([
                Promise.resolve().then(() => task(context.client)),
                timeoutError
            ]);
        }
        finally
        {
            clearTimeout(timeoutId);
        }
    }

    // #endregion

    // #region  S C O P E D   V A L U E   A N D   I N S P E C T I O N

    /**
     * @function _namespaceCacheGet
     * @memberof mcode.cache
     * @desc Gets and decodes one logical key while updating namespace statistics.
     * @param {string} name the namespace name.
     * @param {string} key the logical key.
     * @param {object} client the optional exclusive Redis client.
     * @returns {Promise<*>} the cached value, or undefined when missing.
     * @api private
     */
    async _namespaceCacheGet(name, key, client)
    {
        const physicalKey = this._physicalKey(name, key);
        const namespace = this._getNamespaceInfo(name);
        let value;
        if (namespace.type === 'node')
        {
            value = this.#cache.get(physicalKey);
        }
        else if (client)
        {
            value = this._decodeValue(await client.get(physicalKey));
        }
        else
        {
            value = await this._executeRedis(name, 'GET',
                redisClient => redisClient.get(physicalKey));
            value = this._decodeValue(value);
        }

        if (value === undefined)
        {
            namespace.misses++;
        }
        else
        {
            namespace.hits++;
        }
        return value;
    }

    /**
     * @function _namespaceCacheGetMany
     * @memberof mcode.cache
     * @desc Gets and decodes multiple ordered logical keys.
     * @param {string} name the namespace name.
     * @param {Array<string>} keys the logical keys.
     * @param {object} client the optional exclusive Redis client.
     * @returns {Promise<Array>} the ordered cached values.
     * @api private
     */
    async _namespaceCacheGetMany(name, keys, client)
    {
        if (!Array.isArray(keys) || keys.length === 0)
        {
            throw this._cacheError('CACHE_INVALID_KEY', 'cacheGetMany requires at least one logical key.');
        }
        const physicalKeys = keys.map(key => this._physicalKey(name, key));
        const namespace = this._getNamespaceInfo(name);
        let values;
        if (namespace.type === 'node')
        {
            values = physicalKeys.map(key => this.#cache.get(key));
        }
        else
        {
            const rawValues = client ?
                await client.mGet(physicalKeys) :
                await this._executeRedis(name, 'MGET', redisClient => redisClient.mGet(physicalKeys));
            values = rawValues.map(value => this._decodeValue(value));
        }

        for (const value of values)
        {
            value === undefined ? namespace.misses++ : namespace.hits++;
        }
        return values;
    }

    /**
     * @function _buildSetOptions
     * @memberof mcode.cache
     * @desc Validates package SET options and maps them to native Redis modifiers.
     * @param {object} options the package cacheSet options.
     * @returns {object} the node-redis SET options.
     * @api private
     */
    _buildSetOptions(options = {})
    {
        this._validateOptionsObject(options, 'cacheSet');

        const expirationCount = [
            options.ttlSeconds !== undefined,
            options.ttlMilliseconds !== undefined,
            options.keepTTL === true,
            options.noExpiry === true
        ].filter(Boolean).length;
        if (expirationCount > 1)
        {
            throw this._cacheError('CACHE_INVALID_OPTIONS', 'Select only one cacheSet expiration policy.');
        }
        const conditionCount = [
            options.ifMissing === true,
            options.ifExisting === true,
            options.ifEqual !== undefined
        ].filter(Boolean).length;
        if (conditionCount > 1)
        {
            throw this._cacheError('CACHE_INVALID_OPTIONS', 'Select only one cacheSet condition.');
        }

        const redisOptions = {};
        if (options.ttlSeconds !== undefined)
        {
            this._validatePositiveInteger(options.ttlSeconds, 'ttlSeconds');
            redisOptions.EX = options.ttlSeconds;
        }
        else if (options.ttlMilliseconds !== undefined)
        {
            this._validatePositiveInteger(options.ttlMilliseconds, 'ttlMilliseconds');
            redisOptions.PX = options.ttlMilliseconds;
        }
        else if (options.keepTTL)
        {
            redisOptions.KEEPTTL = true;
        }

        if (options.ifMissing)
        {
            redisOptions.NX = true;
        }
        else if (options.ifExisting)
        {
            redisOptions.XX = true;
        }
        else if (options.ifEqual !== undefined)
        {
            redisOptions.condition = 'IFEQ';
            redisOptions.matchValue = this._encodeValue(options.ifEqual);
        }

        return redisOptions;
    }

    /**
     * @function _namespaceCacheSet
     * @memberof mcode.cache
     * @desc Canonically sets a scoped value with optional native conditions and expiry.
     * @param {string} name the namespace name.
     * @param {string} key the logical key.
     * @param {*} value the supported typed value.
     * @param {object} options the package SET options.
     * @param {object} client the optional exclusive Redis client.
     * @param {number} timeoutMs the optional operation timeout override.
     * @returns {Promise<boolean>} true when the value was set.
     * @api private
     */
    async _namespaceCacheSet(name, key, value, options = {}, client, timeoutMs)
    {
        const physicalKey = this._physicalKey(name, key);
        const namespace = this._getNamespaceInfo(name);
        const encoded = this._encodeValue(value);
        const redisOptions = this._buildSetOptions(options);
        if (namespace.type === 'node')
        {
            if (options.ifMissing && this.#cache.has(physicalKey))
            {
                return false;
            }
            if (options.ifExisting && !this.#cache.has(physicalKey))
            {
                return false;
            }
            const current = this.#cache.get(physicalKey);
            if (options.ifEqual !== undefined && (current === undefined ||
                this._encodeValue(current) !== redisOptions.matchValue))
            {
                return false;
            }
            let ttl = options.ttlSeconds ??
                (options.ttlMilliseconds ? Math.ceil(options.ttlMilliseconds / 1000) : 0);
            if (options.keepTTL && current !== undefined)
            {
                const expiration = this.#cache.getTtl(physicalKey);
                ttl = expiration ? Math.max(1, Math.ceil((expiration - Date.now()) / 1000)) : 0;
            }
            this.#cache.set(physicalKey, this._decodeValue(encoded), ttl);
            return true;
        }

        const reply = client ?
            await client.set(physicalKey, encoded, redisOptions) :
            await this._executeRedis(name, 'SET',
                redisClient => redisClient.set(physicalKey, encoded, redisOptions), true, timeoutMs);
        return reply === 'OK';
    }

    /**
     * @function _namespaceCacheDrop
     * @memberof mcode.cache
     * @desc Deletes one or more scoped logical keys.
     * @param {string} name the namespace name.
     * @param {string|Array<string>} keyOrKeys the logical key or keys.
     * @param {object} client the optional exclusive Redis client.
     * @returns {Promise<number>} the number of deleted keys.
     * @api private
     */
    async _namespaceCacheDrop(name, keyOrKeys, client)
    {
        const keys = Array.isArray(keyOrKeys) ? keyOrKeys : [keyOrKeys];
        if (keys.length === 0)
        {
            return 0;
        }
        const physicalKeys = keys.map(key => this._physicalKey(name, key));
        const namespace = this._getNamespaceInfo(name);
        if (namespace.type === 'node')
        {
            return this.#cache.del(physicalKeys);
        }

        return client ?
            client.del(physicalKeys) :
            this._executeRedis(name, 'DEL', redisClient => redisClient.del(physicalKeys), true);
    }

    /**
     * @function _namespaceCacheDropIfEqual
     * @memberof mcode.cache
     * @desc Deletes one scoped key only when its encoded value matches.
     * @param {string} name the namespace name.
     * @param {string} key the logical key.
     * @param {*} expectedValue the expected typed value.
     * @param {object} client the optional exclusive Redis client.
     * @returns {Promise<boolean>} true when the key was deleted.
     * @api private
     */
    async _namespaceCacheDropIfEqual(name, key, expectedValue, client)
    {
        const physicalKey = this._physicalKey(name, key);
        const encoded = this._encodeValue(expectedValue);
        const namespace = this._getNamespaceInfo(name);
        if (namespace.type === 'node')
        {
            const current = this.#cache.get(physicalKey);
            if (current === undefined || this._encodeValue(current) !== encoded)
            {
                return false;
            }
            return this.#cache.del(physicalKey) === 1;
        }

        const options = {condition: 'IFEQ', matchValue: encoded};
        const reply = client ?
            await client.delEx(physicalKey, options) :
            await this._executeRedis(name, 'DELEX',
                redisClient => redisClient.delEx(physicalKey, options), true);
        return reply === 1;
    }

    /**
     * @function _namespaceCacheExists
     * @memberof mcode.cache
     * @desc Checks whether one scoped logical key exists.
     * @param {string} name the namespace name.
     * @param {string} key the logical key.
     * @param {object} client the optional exclusive Redis client.
     * @returns {Promise<boolean>} true when the key exists.
     * @api private
     */
    async _namespaceCacheExists(name, key, client)
    {
        const physicalKey = this._physicalKey(name, key);
        const namespace = this._getNamespaceInfo(name);
        if (namespace.type === 'node')
        {
            return this.#cache.has(physicalKey);
        }
        const reply = client ?
            await client.exists(physicalKey) :
            await this._executeRedis(name, 'EXISTS', redisClient => redisClient.exists(physicalKey));
        return reply === 1;
    }

    /**
     * @function _namespaceCacheTTL
     * @memberof mcode.cache
     * @desc Reads a scoped key TTL in seconds or milliseconds.
     * @param {string} name the namespace name.
     * @param {string} key the logical key.
     * @param {boolean} milliseconds whether to return PTTL milliseconds.
     * @param {object} client the optional exclusive Redis client.
     * @returns {Promise<number>} the Redis-compatible TTL result.
     * @api private
     */
    async _namespaceCacheTTL(name, key, milliseconds = false, client)
    {
        const physicalKey = this._physicalKey(name, key);
        const namespace = this._getNamespaceInfo(name);
        if (namespace.type === 'node')
        {
            if (!this.#cache.has(physicalKey))
            {
                return -2;
            }
            const expiration = this.#cache.getTtl(physicalKey);
            if (!expiration)
            {
                return -1;
            }
            const ttl = Math.max(0, expiration - Date.now());
            return milliseconds ? ttl : Math.ceil(ttl / 1000);
        }
        const command = milliseconds ? 'PTTL' : 'TTL';
        return client ?
            client[milliseconds ? 'pTTL' : 'ttl'](physicalKey) :
            this._executeRedis(name, command,
                redisClient => redisClient[milliseconds ? 'pTTL' : 'ttl'](physicalKey));
    }

    /**
     * @function _namespaceCacheExpire
     * @memberof mcode.cache
     * @desc Applies an explicit seconds or milliseconds expiry to a scoped key.
     * @param {string} name the namespace name.
     * @param {string} key the logical key.
     * @param {object} options the explicit expiry options.
     * @param {object} client the optional exclusive Redis client.
     * @returns {Promise<boolean>} true when expiry was applied.
     * @api private
     */
    async _namespaceCacheExpire(name, key, options = {}, client)
    {
        this._validateOptionsObject(options, 'cacheExpire');
        const physicalKey = this._physicalKey(name, key);
        const hasSeconds = options.seconds !== undefined;
        const hasMilliseconds = options.milliseconds !== undefined;
        if (hasSeconds === hasMilliseconds)
        {
            throw this._cacheError('CACHE_INVALID_OPTIONS',
                'cacheExpire requires exactly one of seconds or milliseconds.');
        }
        const amount = hasSeconds ? options.seconds : options.milliseconds;
        this._validatePositiveInteger(amount, hasSeconds ? 'seconds' : 'milliseconds');

        const namespace = this._getNamespaceInfo(name);
        if (namespace.type === 'node')
        {
            return this.#cache.ttl(physicalKey, hasSeconds ? amount : Math.ceil(amount / 1000));
        }
        const method = hasSeconds ? 'expire' : 'pExpire';
        const reply = client ?
            await client[method](physicalKey, amount) :
            await this._executeRedis(name, method.toUpperCase(),
                redisClient => redisClient[method](physicalKey, amount), true);
        return reply === 1;
    }

    /**
     * @function _namespacePing
     * @memberof mcode.cache
     * @desc Pings the Redis server for a namespace.
     * @param {string} name the Redis namespace name.
     * @returns {Promise<string>} the Redis PING reply.
     * @api private
     */
    _namespacePing(name)
    {
        return this._executeRedis(name, 'PING', client => client.ping());
    }

    /**
     * @function _namespaceInfo
     * @memberof mcode.cache
     * @desc Reads an allowlisted Redis INFO section.
     * @param {string} name the Redis namespace name.
     * @param {string} section the allowlisted INFO section.
     * @returns {Promise<string>} the Redis INFO response.
     * @api private
     */
    _namespaceInfo(name, section = 'server')
    {
        if (!cache.INFO_SECTIONS.has(section))
        {
            throw this._cacheError('CACHE_INVALID_OPTIONS', `Unsupported INFO section '${section}'.`);
        }
        return this._executeRedis(name, 'INFO', client => client.info(section));
    }

    /**
     * @function _namespaceTime
     * @memberof mcode.cache
     * @desc Reads Redis server time as numeric seconds and microseconds.
     * @param {string} name the Redis namespace name.
     * @returns {Promise<object>} the numeric Redis server time.
     * @api private
     */
    async _namespaceTime(name)
    {
        const reply = await this._executeRedis(name, 'TIME', client => client.time());
        return {
            seconds: Number.parseInt(reply[0], 10),
            microseconds: Number.parseInt(reply[1], 10)
        };
    }

    /**
     * @function _validateScanPattern
     * @memberof mcode.cache
     * @desc Validates a bounded logical SCAN pattern and rejects physical prefixes.
     * @param {string} name the namespace name.
     * @param {string} pattern the logical SCAN pattern.
     * @returns {string} the validated logical pattern.
     * @api private
     */
    _validateScanPattern(name, pattern)
    {
        if (typeof pattern !== 'string' || !pattern ||
            !/^[A-Za-z0-9*._:-]+$/.test(pattern) || pattern.includes('**'))
        {
            throw this._cacheError('CACHE_INVALID_PATTERN',
                'SCAN patterns support only safe logical key characters and single * wildcards.');
        }
        if (pattern === name || pattern.startsWith(`${name}:`))
        {
            throw this._cacheError('CACHE_ALREADY_PREFIXED', 'SCAN patterns must be logical, not namespaced.');
        }
        return pattern;
    }

    /**
     * @function _namespaceScan
     * @memberof mcode.cache
     * @desc Reads one bounded SCAN page and strips the namespace prefix.
     * @param {string} name the Redis namespace name.
     * @param {object} options the cursor, pattern, and count options.
     * @returns {Promise<object>} the next cursor and logical keys.
     * @api private
     */
    async _namespaceScan(name, options = {})
    {
        this._validateOptionsObject(options, 'scan');
        const pattern = this._validateScanPattern(name, options.pattern ?? '*');
        const count = options.count ?? 100;
        if (!Number.isSafeInteger(count) || count < 1 || count > 1000)
        {
            throw this._cacheError('CACHE_INVALID_OPTIONS', 'SCAN count must be between 1 and 1000.');
        }
        const cursor = options.cursor === undefined ? '0' : String(options.cursor);
        if (!/^\d+$/.test(cursor))
        {
            throw this._cacheError('CACHE_INVALID_OPTIONS', 'SCAN cursor must be a non-negative integer string.');
        }

        const prefix = `${name}:`;
        const reply = await this._executeRedis(name, 'SCAN',
            client => client.scan(cursor, {MATCH: `${prefix}${pattern}`, COUNT: count}));
        return {
            cursor: String(reply.cursor),
            keys: reply.keys
                .filter(key => key.startsWith(prefix))
                .map(key => key.slice(prefix.length))
        };
    }

    /**
     * @function _legacyRedisScanKeys
     * @memberof mcode.cache
     * @desc Collects bounded physical keys for deprecated singleton operations.
     * @param {string} name the Redis namespace name.
     * @param {string} pattern the logical key pattern.
     * @param {number} limit the maximum number of keys to collect.
     * @returns {Promise<Array<string>>} the bounded physical Redis keys.
     * @api private
     */
    async _legacyRedisScanKeys(name, pattern, limit)
    {
        let cursor = '0';
        const keys = [];
        do
        {
            const page = await this._namespaceScan(name, {pattern, cursor, count: 1000});
            cursor = page.cursor;
            keys.push(...page.keys.map(key => `${name}:${key}`));
            if (keys.length > limit)
            {
                throw this._cacheError('CACHE_SCAN_LIMIT',
                    `Legacy Redis scan exceeded the bounded limit of ${limit} keys.`);
            }
        }
        while (cursor !== '0');
        return keys;
    }

    /**
     * @function _namespaceInspect
     * @memberof mcode.cache
     * @desc Inspects bounded scoped keys with type and optional string value.
     * @param {string} name the Redis namespace name.
     * @param {object} options the bounded inspection options.
     * @returns {Promise<object>} the next cursor and inspected entries.
     * @api private
     */
    async _namespaceInspect(name, options = {})
    {
        this._validateOptionsObject(options, 'inspect');
        const limit = options.limit ?? 100;
        if (!Number.isSafeInteger(limit) || limit < 1 || limit > 1000)
        {
            throw this._cacheError('CACHE_INVALID_OPTIONS', 'Inspection limit must be between 1 and 1000.');
        }

        let cursor = options.cursor === undefined ? '0' : String(options.cursor);
        const keys = [];
        do
        {
            const page = await this._namespaceScan(name, {
                pattern: options.pattern ?? '*',
                cursor,
                count: Math.min(options.count ?? 100, 1000)
            });
            cursor = page.cursor;
            for (const key of page.keys)
            {
                const physicalKey = this._physicalKey(name, key);
                const type = await this._executeRedis(name, 'TYPE',
                    client => client.type(physicalKey));
                const entry = {key, type};
                if (options.includeValue === true && type === 'string')
                {
                    entry.value = await this._namespaceCacheGet(name, key);
                }
                keys.push(entry);
                if (keys.length >= limit)
                {
                    break;
                }
            }
        }
        while (cursor !== '0' && keys.length < limit);

        return {cursor, entries: keys};
    }

    // #endregion

    // #region  G E O   A N D   S O R T E D   S E T S

    /**
     * @function _validateMember
     * @memberof mcode.cache
     * @desc Validates a geo or sorted-set member string.
     * @param {string} member the member to validate.
     * @returns {string} the validated member.
     * @api private
     */
    _validateMember(member)
    {
        if (typeof member !== 'string' || !member ||
            Buffer.byteLength(member, 'utf8') > cache.MAX_LOGICAL_KEY_BYTES ||
            /[\u0000-\u001f\u007f]/.test(member))
        {
            throw this._cacheError('CACHE_INVALID_MEMBER',
                'Members must be non-empty strings without control characters and no larger than 512 bytes.');
        }
        return member;
    }

    /**
     * @function _normalizeGeoMembers
     * @memberof mcode.cache
     * @desc Validates and normalizes one or more geo members.
     * @param {object|Array<object>} members the geo members to normalize.
     * @returns {Array<object>} the normalized geo members.
     * @api private
     */
    _normalizeGeoMembers(members)
    {
        const normalized = Array.isArray(members) ? members : [members];
        if (normalized.length === 0)
        {
            throw this._cacheError('CACHE_INVALID_OPTIONS', 'geoAdd requires at least one member.');
        }
        return normalized.map(item =>
        {
            if (!item || typeof item !== 'object' ||
                typeof item.longitude !== 'number' || !Number.isFinite(item.longitude) ||
                typeof item.latitude !== 'number' || !Number.isFinite(item.latitude) ||
                item.longitude < -180 || item.longitude > 180 ||
                item.latitude < -85.05112878 || item.latitude > 85.05112878)
            {
                throw this._cacheError('CACHE_INVALID_COORDINATE',
                    'Geo members require finite longitude [-180,180] and latitude [-85.05112878,85.05112878].');
            }
            return {
                longitude: item.longitude,
                latitude: item.latitude,
                member: this._validateMember(item.member)
            };
        });
    }

    /**
     * @function _namespaceGeoAdd
     * @memberof mcode.cache
     * @desc Adds one or more members to a scoped geo index.
     * @param {string} name the Redis namespace name.
     * @param {string} key the logical geo key.
     * @param {object|Array<object>} members the geo members.
     * @param {object} client the optional exclusive Redis client.
     * @returns {Promise<number>} the number of added members.
     * @api private
     */
    async _namespaceGeoAdd(name, key, members, client)
    {
        const physicalKey = this._physicalKey(name, key);
        const normalized = this._normalizeGeoMembers(members);
        return client ?
            client.geoAdd(physicalKey, normalized) :
            this._executeRedis(name, 'GEOADD',
                redisClient => redisClient.geoAdd(physicalKey, normalized), true);
    }

    /**
     * @function _namespaceGeoRemove
     * @memberof mcode.cache
     * @desc Removes one or more members from a scoped geo index.
     * @param {string} name the Redis namespace name.
     * @param {string} key the logical geo key.
     * @param {string|Array<string>} members the members to remove.
     * @param {object} client the optional exclusive Redis client.
     * @returns {Promise<number>} the number of removed members.
     * @api private
     */
    async _namespaceGeoRemove(name, key, members, client)
    {
        const physicalKey = this._physicalKey(name, key);
        const normalized = (Array.isArray(members) ? members : [members])
            .map(member => this._validateMember(member));
        if (normalized.length === 0)
        {
            return 0;
        }
        return client ?
            client.zRem(physicalKey, normalized) :
            this._executeRedis(name, 'ZREM',
                redisClient => redisClient.zRem(physicalKey, normalized), true);
    }

    /**
     * @function _namespaceGeoSearch
     * @memberof mcode.cache
     * @desc Searches a scoped geo index by member, radius, or box.
     * @param {string} name the Redis namespace name.
     * @param {string} key the logical geo key.
     * @param {object} options the bounded geo search options.
     * @returns {Promise<Array<string>>} the matching members.
     * @api private
     */
    async _namespaceGeoSearch(name, key, options = {})
    {
        this._validateOptionsObject(options, 'geoSearch');
        const physicalKey = this._physicalKey(name, key);
        let from;
        if (options.from?.member)
        {
            from = this._validateMember(options.from.member);
        }
        else if (options.from && Number.isFinite(options.from.longitude) &&
            Number.isFinite(options.from.latitude))
        {
            this._normalizeGeoMembers([{
                longitude: options.from.longitude,
                latitude: options.from.latitude,
                member: 'origin'
            }]);
            from = {longitude: options.from.longitude, latitude: options.from.latitude};
        }
        else
        {
            throw this._cacheError('CACHE_INVALID_OPTIONS',
                'geoSearch requires from.member or finite from.longitude/from.latitude.');
        }

        if (!cache.GEO_UNITS.has(options.unit))
        {
            throw this._cacheError('CACHE_INVALID_OPTIONS', 'geoSearch unit must be m, km, mi, or ft.');
        }

        let by;
        if (Number.isFinite(options.radius) && options.radius > 0)
        {
            by = {radius: options.radius, unit: options.unit};
        }
        else if (Number.isFinite(options.width) && options.width > 0 &&
            Number.isFinite(options.height) && options.height > 0)
        {
            by = {width: options.width, height: options.height, unit: options.unit};
        }
        else
        {
            throw this._cacheError('CACHE_INVALID_OPTIONS',
                'geoSearch requires a positive radius or positive width and height.');
        }

        const redisOptions = {};
        if (options.sort !== undefined)
        {
            if (options.sort !== 'ASC' && options.sort !== 'DESC')
            {
                throw this._cacheError('CACHE_INVALID_OPTIONS', 'geoSearch sort must be ASC or DESC.');
            }
            redisOptions.SORT = options.sort;
        }
        if (options.count !== undefined)
        {
            this._validatePositiveInteger(options.count, 'geoSearch count');
            redisOptions.COUNT = options.any ? {value: options.count, ANY: true} : options.count;
        }

        return this._executeRedis(name, 'GEOSEARCH',
            client => client.geoSearch(physicalKey, from, by, redisOptions));
    }

    /**
     * @function _normalizeSortedSetMembers
     * @memberof mcode.cache
     * @desc Validates and normalizes one or more sorted-set members.
     * @param {object|Array<object>} members the scored members to normalize.
     * @returns {Array<object>} the normalized node-redis members.
     * @api private
     */
    _normalizeSortedSetMembers(members)
    {
        const normalized = Array.isArray(members) ? members : [members];
        if (normalized.length === 0)
        {
            throw this._cacheError('CACHE_INVALID_OPTIONS', 'sortedSetAdd requires at least one member.');
        }
        return normalized.map(item =>
        {
            if (!item || !Number.isFinite(item.score))
            {
                throw this._cacheError('CACHE_INVALID_SCORE', 'Sorted-set scores must be finite numbers.');
            }
            return {score: item.score, value: this._validateMember(item.member ?? item.value)};
        });
    }

    /**
     * @function _buildSortedSetOptions
     * @memberof mcode.cache
     * @desc Maps package sorted-set conditions to native Redis modifiers.
     * @param {object} options the sortedSetAdd options.
     * @returns {object} the node-redis ZADD options.
     * @api private
     */
    _buildSortedSetOptions(options = {})
    {
        this._validateOptionsObject(options, 'sortedSetAdd');
        const conditionCount = [options.ifMissing, options.ifExisting].filter(Boolean).length;
        if (conditionCount > 1)
        {
            throw this._cacheError('CACHE_INVALID_OPTIONS',
                'sortedSetAdd accepts only one of ifMissing or ifExisting.');
        }
        const reply = {};
        if (options.ifMissing)
        {
            reply.NX = true;
        }
        if (options.ifExisting)
        {
            reply.XX = true;
        }
        if (options.changed)
        {
            reply.CH = true;
        }
        return reply;
    }

    /**
     * @function _namespaceSortedSetAdd
     * @memberof mcode.cache
     * @desc Adds scored members to a scoped sorted set.
     * @param {string} name the Redis namespace name.
     * @param {string} key the logical sorted-set key.
     * @param {object|Array<object>} members the scored members.
     * @param {object} options the package ZADD options.
     * @param {object} client the optional exclusive Redis client.
     * @returns {Promise<number>} the Redis ZADD result.
     * @api private
     */
    async _namespaceSortedSetAdd(name, key, members, options = {}, client)
    {
        const physicalKey = this._physicalKey(name, key);
        const normalized = this._normalizeSortedSetMembers(members);
        const redisOptions = this._buildSortedSetOptions(options);
        return client ?
            client.zAdd(physicalKey, normalized, redisOptions) :
            this._executeRedis(name, 'ZADD',
                redisClient => redisClient.zAdd(physicalKey, normalized, redisOptions), true);
    }

    /**
     * @function _namespaceSortedSetRemove
     * @memberof mcode.cache
     * @desc Removes members from a scoped sorted set.
     * @param {string} name the Redis namespace name.
     * @param {string} key the logical sorted-set key.
     * @param {string|Array<string>} members the members to remove.
     * @param {object} client the optional exclusive Redis client.
     * @returns {Promise<number>} the number of removed members.
     * @api private
     */
    async _namespaceSortedSetRemove(name, key, members, client)
    {
        const physicalKey = this._physicalKey(name, key);
        const normalized = (Array.isArray(members) ? members : [members])
            .map(member => this._validateMember(member));
        return client ?
            client.zRem(physicalKey, normalized) :
            this._executeRedis(name, 'ZREM',
                redisClient => redisClient.zRem(physicalKey, normalized), true);
    }

    /**
     * @function _namespaceSortedSetRange
     * @memberof mcode.cache
     * @desc Reads an index range from a scoped sorted set.
     * @param {string} name the Redis namespace name.
     * @param {string} key the logical sorted-set key.
     * @param {object} options the range, reverse, and score-return options.
     * @returns {Promise<Array>} the members or member-score objects.
     * @api private
     */
    async _namespaceSortedSetRange(name, key, options = {})
    {
        this._validateOptionsObject(options, 'sortedSetRange');
        const physicalKey = this._physicalKey(name, key);
        const start = options.start ?? 0;
        const stop = options.stop ?? -1;
        if (!Number.isSafeInteger(start) || !Number.isSafeInteger(stop))
        {
            throw this._cacheError('CACHE_INVALID_OPTIONS', 'Sorted-set range indexes must be integers.');
        }
        const redisOptions = options.reverse ? {REV: true} : {};
        const method = options.withScores ? 'zRangeWithScores' : 'zRange';
        const results = await this._executeRedis(name, 'ZRANGE',
            client => client[method](physicalKey, start, stop, redisOptions));
        return options.withScores ?
            results.map(item => ({member: item.value, score: item.score})) :
            results;
    }

    /**
     * @function _namespaceSortedSetRangeByScore
     * @memberof mcode.cache
     * @desc Reads a bounded score range from a scoped sorted set.
     * @param {string} name the Redis namespace name.
     * @param {string} key the logical sorted-set key.
     * @param {object} options the score bounds, limit, and score-return options.
     * @returns {Promise<Array>} the members or member-score objects.
     * @api private
     */
    async _namespaceSortedSetRangeByScore(name, key, options = {})
    {
        this._validateOptionsObject(options, 'sortedSetRangeByScore');
        const physicalKey = this._physicalKey(name, key);
        const min = options.min ?? '-inf';
        const max = options.max ?? '+inf';
        const redisOptions = {};
        if (options.offset !== undefined || options.count !== undefined)
        {
            if (!Number.isSafeInteger(options.offset) || options.offset < 0 ||
                !Number.isSafeInteger(options.count) || options.count <= 0)
            {
                throw this._cacheError('CACHE_INVALID_OPTIONS',
                    'Score range offset must be non-negative and count must be positive.');
            }
            redisOptions.LIMIT = {offset: options.offset, count: options.count};
        }
        const method = options.withScores ? 'zRangeByScoreWithScores' : 'zRangeByScore';
        const results = await this._executeRedis(name, 'ZRANGEBYSCORE',
            client => client[method](physicalKey, min, max, redisOptions));
        return options.withScores ?
            results.map(item => ({member: item.value, score: item.score})) :
            results;
    }

    /**
     * @function _namespaceSortedSetRank
     * @memberof mcode.cache
     * @desc Reads the forward or reverse rank of a scoped sorted-set member.
     * @param {string} name the Redis namespace name.
     * @param {string} key the logical sorted-set key.
     * @param {string} member the member to rank.
     * @param {boolean} reverse whether to use reverse rank.
     * @returns {Promise<number|null>} the member rank, or null when missing.
     * @api private
     */
    async _namespaceSortedSetRank(name, key, member, reverse = false)
    {
        const physicalKey = this._physicalKey(name, key);
        const method = reverse ? 'zRevRank' : 'zRank';
        return this._executeRedis(name, reverse ? 'ZREVRANK' : 'ZRANK',
            client => client[method](physicalKey, this._validateMember(member)));
    }

    /**
     * @function _namespaceSortedSetScore
     * @memberof mcode.cache
     * @desc Reads the score of a scoped sorted-set member.
     * @param {string} name the Redis namespace name.
     * @param {string} key the logical sorted-set key.
     * @param {string} member the member to read.
     * @returns {Promise<number|null>} the member score, or null when missing.
     * @api private
     */
    async _namespaceSortedSetScore(name, key, member)
    {
        const physicalKey = this._physicalKey(name, key);
        return this._executeRedis(name, 'ZSCORE',
            client => client.zScore(physicalKey, this._validateMember(member)));
    }

    // #endregion

    // #region  T R A N S A C T I O N S   A N D   G E N E R A T I O N

    /**
     * @function _createMultiBuilder
     * @memberof mcode.cache
     * @desc Creates a typed transaction builder without exposing raw Redis commands.
     * @param {string} name the Redis namespace name.
     * @param {object} client the optional exclusive Redis client.
     * @param {boolean} deferred whether WATCH owns transaction execution.
     * @returns {object} the frozen typed transaction builder.
     * @api private
     */
    _createMultiBuilder(name, client = null, deferred = false)
    {
        const namespace = this._getNamespaceInfo(name);
        if (!namespace || namespace.type !== 'redis')
        {
            throw this._cacheError('CACHE_REDIS_REQUIRED', 'Transactions require a Redis namespace.');
        }

        const operations = [];
        let executed = false;
        const queue = (method, args) =>
        {
            if (executed)
            {
                throw this._cacheError('CACHE_TRANSACTION_CLOSED', 'This transaction builder was already executed.');
            }
            operations.push({method, args});
            return builder;
        };
        const builder = {
            cacheGet: key => queue('cacheGet', [key]),
            cacheSet: (key, value, options) => queue('cacheSet', [key, value, options]),
            cacheDrop: keyOrKeys => queue('cacheDrop', [keyOrKeys]),
            cacheDropIfEqual: (key, expectedValue) => queue('cacheDropIfEqual', [key, expectedValue]),
            cacheExists: key => queue('cacheExists', [key]),
            cacheExpire: (key, options) => queue('cacheExpire', [key, options]),
            geoAdd: (key, members) => queue('geoAdd', [key, members]),
            geoRemove: (key, members) => queue('geoRemove', [key, members]),
            sortedSetAdd: (key, members, options) => queue('sortedSetAdd', [key, members, options]),
            sortedSetRemove: (key, members) => queue('sortedSetRemove', [key, members]),
            publish: (channel, value) => queue('publish', [channel, value]),
            exec: async () =>
            {
                if (deferred)
                {
                    throw this._cacheError('CACHE_TRANSACTION_DEFERRED',
                        'WATCH transaction planners must return the builder; they cannot execute it directly.');
                }
                executed = true;
                return this._executeMultiOperations(name, operations, client);
            }
        };
        Object.freeze(builder);
        this.#multiOperations.set(builder, operations);
        return builder;
    }

    /**
     * @function _appendMultiOperation
     * @memberof mcode.cache
     * @desc Validates and appends one typed operation to a node-redis MULTI.
     * @param {string} name the Redis namespace name.
     * @param {object} multi the node-redis MULTI builder.
     * @param {object} operation the queued typed operation.
     * @returns {function} the reply transformation function.
     * @api private
     */
    _appendMultiOperation(name, multi, operation)
    {
        const args = operation.args;
        switch (operation.method)
        {
            case 'cacheGet':
                multi.get(this._physicalKey(name, args[0]));
                return value => this._decodeValue(value);
            case 'cacheSet':
                multi.set(this._physicalKey(name, args[0]), this._encodeValue(args[1]),
                    this._buildSetOptions(args[2]));
                return value => value === 'OK';
            case 'cacheDrop':
            {
                const keys = (Array.isArray(args[0]) ? args[0] : [args[0]])
                    .map(key => this._physicalKey(name, key));
                multi.del(keys);
                return value => value;
            }
            case 'cacheDropIfEqual':
                multi.delEx(this._physicalKey(name, args[0]), {
                    condition: 'IFEQ',
                    matchValue: this._encodeValue(args[1])
                });
                return value => value === 1;
            case 'cacheExists':
                multi.exists(this._physicalKey(name, args[0]));
                return value => value === 1;
            case 'cacheExpire':
            {
                const options = args[1] || {};
                const hasSeconds = options.seconds !== undefined;
                const hasMilliseconds = options.milliseconds !== undefined;
                if (hasSeconds === hasMilliseconds)
                {
                    throw this._cacheError('CACHE_INVALID_OPTIONS',
                        'cacheExpire requires exactly one of seconds or milliseconds.');
                }
                const amount = hasSeconds ? options.seconds : options.milliseconds;
                this._validatePositiveInteger(amount, hasSeconds ? 'seconds' : 'milliseconds');
                multi[hasSeconds ? 'expire' : 'pExpire'](this._physicalKey(name, args[0]), amount);
                return value => value === 1;
            }
            case 'geoAdd':
                multi.geoAdd(this._physicalKey(name, args[0]), this._normalizeGeoMembers(args[1]));
                return value => value;
            case 'geoRemove':
                multi.zRem(this._physicalKey(name, args[0]),
                    (Array.isArray(args[1]) ? args[1] : [args[1]]).map(member => this._validateMember(member)));
                return value => value;
            case 'sortedSetAdd':
                multi.zAdd(this._physicalKey(name, args[0]), this._normalizeSortedSetMembers(args[1]),
                    this._buildSortedSetOptions(args[2]));
                return value => value;
            case 'sortedSetRemove':
                multi.zRem(this._physicalKey(name, args[0]),
                    (Array.isArray(args[1]) ? args[1] : [args[1]]).map(member => this._validateMember(member)));
                return value => value;
            case 'publish':
                multi.publish(this._physicalChannel(name, args[0]), this._encodeValue(args[1]));
                return value => value;
            default:
                throw this._cacheError('CACHE_TRANSACTION_COMMAND',
                    `Unsupported transaction operation '${operation.method}'.`);
        }
    }

    /**
     * @function _executeMultiOperations
     * @memberof mcode.cache
     * @desc Executes typed MULTI operations and normalizes every command reply.
     * @param {string} name the Redis namespace name.
     * @param {Array<object>} operations the queued typed operations.
     * @param {object} client the optional exclusive Redis client.
     * @returns {Promise<Array<object>>} the normalized result/error envelopes.
     * @api private
     */
    async _executeMultiOperations(name, operations, client)
    {
        if (operations.length === 0)
        {
            return [];
        }

        const execute = async redisClient =>
        {
            const multi = redisClient.multi();
            const transforms = operations.map(operation =>
                this._appendMultiOperation(name, multi, operation));
            let replies;
            try
            {
                replies = await multi.exec();
            }
            catch (error)
            {
                if (!Array.isArray(error.replies))
                {
                    throw error;
                }
                replies = error.replies;
            }

            return replies.map((reply, index) =>
            {
                if (reply instanceof Error)
                {
                    return {
                        result: undefined,
                        error: {code: reply.code || 'CACHE_TRANSACTION_COMMAND', message: reply.message}
                    };
                }
                return {result: transforms[index](reply), error: null};
            });
        };

        return client ?
            execute(client) :
            this._executeRedis(name, 'MULTI/EXEC', execute, true);
    }

    /**
     * @function _assertTransactionReplies
     * @memberof mcode.cache
     * @desc Throws the first normalized transaction command error.
     * @param {Array<object>} replies the normalized transaction replies.
     * @param {string} operation the transaction operation name.
     * @returns {Array<object>} the successful replies.
     * @api private
     */
    _assertTransactionReplies(replies, operation)
    {
        const failure = replies.find(reply => reply.error);
        if (failure)
        {
            throw this._cacheError(
                failure.error.code || 'CACHE_TRANSACTION_COMMAND',
                `${operation} failed: ${failure.error.message}`
            );
        }
        return replies;
    }

    /**
     * @function _watchTransaction
     * @memberof mcode.cache
     * @desc Executes a bounded optimistic transaction on an exclusive connection.
     * @param {string} name the Redis namespace name.
     * @param {object} options the watched keys, retry, and deadline options.
     * @param {function} planner the side-effect-free transaction planner.
     * @returns {Promise<Array<object>>} the normalized EXEC replies.
     * @api private
     */
    async _watchTransaction(name, options, planner)
    {
        if (!options || typeof options !== 'object' || !Array.isArray(options.keys) ||
            options.keys.length === 0)
        {
            throw this._cacheError('CACHE_INVALID_OPTIONS',
                'watchTransaction requires a non-empty logical keys array.');
        }
        this._validatePositiveInteger(options.deadlineMs, 'deadlineMs');
        if (!Number.isSafeInteger(options.maxRetries) || options.maxRetries < 0)
        {
            throw this._cacheError('CACHE_INVALID_OPTIONS', 'maxRetries must be a non-negative integer.');
        }
        if (typeof planner !== 'function')
        {
            throw this._cacheError('CACHE_INVALID_OPTIONS', 'watchTransaction planner must be a function.');
        }

        const context = this.#redisContexts.get(name);
        const expiresAt = Date.now() + options.deadlineMs;
        await this._namespaceReady(name, {
            timeoutMs: Math.min(this._remainingDeadline(expiresAt, 'WATCH transaction'),
                context.config.readyTimeoutMs)
        });
        const transactionClient = context.client.duplicate();
        transactionClient.on('error', () => undefined);
        context.transactionClients.add(transactionClient);

        try
        {
            await this._withTimeout(transactionClient.connect(),
                this._remainingDeadline(expiresAt, 'WATCH connection'),
                `WATCH connection for '${name}'`);
            await this._withTimeout(this._verifyRedisCapabilities(transactionClient, context.config),
                this._remainingDeadline(expiresAt, 'WATCH capability check'),
                `WATCH capability check for '${name}'`);
            const physicalKeys = options.keys.map(key => this._physicalKey(name, key));

            for (let attempt = 0; attempt <= options.maxRetries; attempt++)
            {
                if (Date.now() >= expiresAt)
                {
                    throw this._cacheError('CACHE_TIMEOUT', 'WATCH transaction deadline expired.');
                }

                try
                {
                    await this._withTimeout(transactionClient.watch(physicalKeys),
                        this._remainingDeadline(expiresAt, 'WATCH'), 'WATCH');
                    const builder = this._createMultiBuilder(name, transactionClient, true);
                    const session = Object.freeze({
                        cacheGet: key => this._namespaceCacheGet(name, key, transactionClient),
                        cacheGetMany: keys => this._namespaceCacheGetMany(name, keys, transactionClient),
                        cacheExists: key => this._namespaceCacheExists(name, key, transactionClient),
                        cacheTTL: key => this._namespaceCacheTTL(name, key, false, transactionClient),
                        cachePTTL: key => this._namespaceCacheTTL(name, key, true, transactionClient),
                        multi: () => builder
                    });
                    const planned = await this._withTimeout(Promise.resolve(planner(session, attempt)),
                        this._remainingDeadline(expiresAt, 'WATCH planner'), 'WATCH planner');
                    const operations = this.#multiOperations.get(planned);
                    if (!operations)
                    {
                        await transactionClient.unwatch();
                        throw this._cacheError('CACHE_TRANSACTION_PLAN',
                            'WATCH planner must return the builder created by session.multi().');
                    }
                    if (operations.length === 0)
                    {
                        await transactionClient.unwatch();
                        return [];
                    }
                    return await this._withTimeout(
                        this._executeMultiOperations(name, operations, transactionClient),
                        this._remainingDeadline(expiresAt, 'WATCH MULTI/EXEC'), 'WATCH MULTI/EXEC');
                }
                catch (error)
                {
                    const isWatchError = error.name === 'WatchError' ||
                        error.constructor?.name === 'WatchError' ||
                        /watched keys? (?:has|have) been changed/i.test(error.message);
                    if (!isWatchError)
                    {
                        throw error;
                    }
                    if (attempt === options.maxRetries)
                    {
                        throw this._cacheError('CACHE_WATCH_CONTENTION',
                            `WATCH transaction exceeded ${options.maxRetries} retries.`, error);
                    }
                }
            }
        }
        finally
        {
            context.transactionClients.delete(transactionClient);
            await this._closeRedisClient(transactionClient, context.config.commandTimeoutMs);
        }
    }

    /**
     * @function _validateGenerationOptions
     * @memberof mcode.cache
     * @desc Validates generation marker identity options shared by ensure and reset.
     * @param {object} options the generation options.
     * @returns {object} the validated generation options.
     * @api private
     */
    _validateGenerationOptions(options)
    {
        if (!options || typeof options !== 'object')
        {
            throw this._cacheError('CACHE_INVALID_OPTIONS', 'Generation options must be an object.');
        }
        this._validateLogicalName(options.markerKey);
        const validGeneration = (typeof options.generation === 'string' && options.generation.length > 0) ||
            (typeof options.generation === 'number' && Number.isFinite(options.generation));
        if (!validGeneration)
        {
            throw this._cacheError('CACHE_INVALID_OPTIONS',
                'Generation must be a non-empty string or finite number.');
        }
        return options;
    }

    /**
     * @function _ensureGeneration
     * @memberof mcode.cache
     * @desc Checks whether a namespace has the requested ready generation marker.
     * @param {string} name the Redis namespace name.
     * @param {object} options the generation marker options.
     * @returns {Promise<object>} the current flag and stored marker.
     * @api private
     */
    async _ensureGeneration(name, options)
    {
        this._validateGenerationOptions(options);
        const marker = await this._namespaceCacheGet(name, options.markerKey);
        return {
            current: marker?.state === 'ready' && marker?.generation === options.generation,
            marker
        };
    }

    /**
     * @function _resetGeneration
     * @memberof mcode.cache
     * @desc Performs a guarded, bounded, atomic, and verified namespace reset.
     * @param {string} name the Redis namespace name.
     * @param {object} options the explicit guard, generation, limit, and deadline options.
     * @returns {Promise<object>} the reset status, generation, and deleted-key count.
     * @api private
     */
    async _resetGeneration(name, options)
    {
        this._validateGenerationOptions(options);
        this._validateLogicalName(options.guardKey);
        if (options.guardKey === options.markerKey)
        {
            throw this._cacheError('CACHE_INVALID_OPTIONS', 'Generation guard and marker keys must differ.');
        }
        if (typeof options.guardToken !== 'string' || !options.guardToken)
        {
            throw this._cacheError('CACHE_INVALID_OPTIONS', 'Generation guardToken must be a non-empty string.');
        }
        this._validatePositiveInteger(options.guardTtlMilliseconds, 'guardTtlMilliseconds');
        this._validatePositiveInteger(options.deadlineMs, 'deadlineMs');
        this._validatePositiveInteger(options.scanCount, 'scanCount');
        this._validatePositiveInteger(options.maxKeys, 'maxKeys');
        if (options.guardTtlMilliseconds < options.deadlineMs)
        {
            throw this._cacheError('CACHE_INVALID_OPTIONS',
                'guardTtlMilliseconds must cover the complete generation reset deadline.');
        }
        if (!Number.isSafeInteger(options.maxRetries) || options.maxRetries < 0)
        {
            throw this._cacheError('CACHE_INVALID_OPTIONS', 'maxRetries must be a non-negative integer.');
        }
        if (typeof options.acquireGuard !== 'boolean' || typeof options.releaseGuard !== 'boolean')
        {
            throw this._cacheError('CACHE_INVALID_OPTIONS',
                'acquireGuard and releaseGuard must be explicit booleans.');
        }

        const expiresAt = Date.now() + options.deadlineMs;
        if (options.acquireGuard)
        {
            const guardAcquired = await this._namespaceCacheSet(name, options.guardKey, options.guardToken, {
                ifMissing: true,
                ttlMilliseconds: options.guardTtlMilliseconds
            }, undefined, this._remainingDeadline(expiresAt, 'Generation guard acquisition'));
            if (!guardAcquired)
            {
                const owner = await this._namespaceCacheGet(name, options.guardKey);
                if (owner !== options.guardToken)
                {
                    throw this._cacheError('CACHE_GENERATION_GUARD',
                        'Generation reset guard is owned by another caller.');
                }
            }
        }
        else if (await this._namespaceCacheGet(name, options.guardKey) !== options.guardToken)
        {
            throw this._cacheError('CACHE_GENERATION_GUARD', 'Generation reset guard is missing or not owned.');
        }

        try
        {
            const current = await this._ensureGeneration(name, options);
            if (current.current)
            {
                return {changed: false, generation: options.generation, deleted: 0};
            }

            const keysToDelete = new Set();
            let cursor = '0';
            do
            {
                const page = await this._namespaceScan(name, {
                    pattern: '*',
                    cursor,
                    count: Math.min(options.scanCount, 1000)
                });
                cursor = page.cursor;
                for (const key of page.keys)
                {
                    if (key !== options.guardKey && key !== options.markerKey)
                    {
                        keysToDelete.add(key);
                        if (keysToDelete.size > options.maxKeys)
                        {
                            throw this._cacheError('CACHE_GENERATION_LIMIT',
                                `Generation reset exceeded maxKeys ${options.maxKeys}.`);
                        }
                    }
                }
                if (Date.now() >= expiresAt)
                {
                    throw this._cacheError('CACHE_TIMEOUT', 'Generation reset deadline expired during inspection.');
                }
            }
            while (cursor !== '0');

            const pending = {
                generation: options.generation,
                state: 'pending',
                guardToken: options.guardToken
            };
            const ready = {generation: options.generation, state: 'ready'};
            const resetReplies = await this._watchTransaction(name, {
                keys: [options.guardKey, options.markerKey],
                maxRetries: options.maxRetries,
                deadlineMs: this._remainingDeadline(expiresAt, 'Generation reset transaction')
            }, async transaction =>
            {
                const [guard, guardTtl] = await Promise.all([
                    transaction.cacheGet(options.guardKey),
                    transaction.cachePTTL(options.guardKey)
                ]);
                if (guard !== options.guardToken)
                {
                    throw this._cacheError('CACHE_GENERATION_GUARD',
                        'Generation reset guard changed before commit.');
                }
                if (guardTtl < this._remainingDeadline(expiresAt, 'Generation reset guard'))
                {
                    throw this._cacheError('CACHE_GENERATION_GUARD',
                        'Generation reset guard TTL is insufficient for the remaining deadline.');
                }

                const multi = transaction.multi();
                const keys = Array.from(keysToDelete);
                for (let index = 0; index < keys.length; index += cache.TRANSACTION_DELETE_BATCH_SIZE)
                {
                    multi.cacheDrop(keys.slice(index, index + cache.TRANSACTION_DELETE_BATCH_SIZE));
                }
                return multi.cacheSet(options.markerKey, pending, {noExpiry: true});
            });
            this._assertTransactionReplies(resetReplies, 'Generation reset transaction');

            const unexpected = new Set();
            let verificationCursor = '0';
            do
            {
                const verificationPage = await this._namespaceScan(name, {
                    pattern: '*',
                    cursor: verificationCursor,
                    count: Math.min(options.scanCount, 1000)
                });
                verificationCursor = verificationPage.cursor;
                for (const key of verificationPage.keys)
                {
                    if (key !== options.markerKey && key !== options.guardKey)
                    {
                        unexpected.add(key);
                    }
                }
                if (Date.now() >= expiresAt)
                {
                    throw this._cacheError('CACHE_TIMEOUT',
                        'Generation reset deadline expired during verification.');
                }
            }
            while (verificationCursor !== '0');
            const marker = await this._namespaceCacheGet(name, options.markerKey);
            if (unexpected.size > 0 || this._encodeValue(marker) !== this._encodeValue(pending))
            {
                throw this._cacheError('CACHE_GENERATION_VERIFY',
                    'Generation reset verification failed; the marker remains pending.');
            }

            const promoted = await this._namespaceCacheSet(
                name,
                options.markerKey,
                ready,
                {ifEqual: pending, noExpiry: true},
                undefined,
                this._remainingDeadline(expiresAt, 'Generation ready promotion')
            );
            if (!promoted)
            {
                throw this._cacheError('CACHE_GENERATION_VERIFY',
                    'Generation marker changed before native ready promotion.');
            }
            const promotedMarker = await this._namespaceCacheGet(name, options.markerKey);
            if (this._encodeValue(promotedMarker) !== this._encodeValue(ready))
            {
                throw this._cacheError('CACHE_GENERATION_VERIFY',
                    'Generation ready marker verification failed.');
            }

            return {changed: true, generation: options.generation, deleted: keysToDelete.size};
        }
        finally
        {
            if (options.releaseGuard)
            {
                await this._namespaceCacheDropIfEqual(name, options.guardKey, options.guardToken)
                    .catch(error => _log.warn(`Failed to release generation guard: ${error.message}`, MODULE_NAME));
            }
        }
    }

    // #endregion

    // #region  P U B S U B   A N D   R E S O U R C E   C L E A N U P

    /**
     * @function _namespacePublish
     * @memberof mcode.cache
     * @desc Publishes one encoded typed value on a scoped Redis channel.
     * @param {string} name the Redis namespace name.
     * @param {string} channel the logical channel.
     * @param {*} value the supported typed message value.
     * @returns {Promise<number>} the number of receiving subscribers.
     * @api private
     */
    _namespacePublish(name, channel, value)
    {
        const physicalChannel = this._physicalChannel(name, channel);
        const encoded = this._encodeValue(value);
        return this._executeRedis(name, 'PUBLISH',
            client => client.publish(physicalChannel, encoded), true);
    }

    /**
     * @function _createSubscriber
     * @memberof mcode.cache
     * @desc Creates an isolated, tracked, and immutable subscriber handle.
     * @param {string} name the Redis namespace name.
     * @param {object} options the bounded subscriber readiness options.
     * @returns {Promise<object>} the immutable subscriber handle.
     * @api private
     */
    async _createSubscriber(name, options = {})
    {
        this._validateOptionsObject(options, 'createSubscriber');
        const context = this.#redisContexts.get(name);
        if (!context)
        {
            throw this._cacheError('CACHE_REDIS_REQUIRED', 'Subscribers require a Redis namespace.');
        }
        const timeoutMs = options.timeoutMs ?? context.config.readyTimeoutMs;
        this._validatePositiveInteger(timeoutMs, 'subscriber timeoutMs');
        await this._namespaceReady(name, {timeoutMs});

        const subscriber = context.client.duplicate();
        subscriber.on('error', error =>
            _log.warn(`Redis subscriber '${name}' error: ${error.message}`, MODULE_NAME));
        try
        {
            await this._withTimeout(subscriber.connect(), timeoutMs, `Subscriber readiness for '${name}'`);
            await this._withTimeout(this._verifyRedisCapabilities(subscriber, context.config),
                timeoutMs, `Subscriber capability check for '${name}'`);
        }
        catch (error)
        {
            await this._closeRedisClient(subscriber, timeoutMs);
            throw error;
        }

        const registrations = new Map();
        let closed = false;
        let closePromise = null;
        const handle = {
            get closed()
            {
                return closed;
            },
            subscribe: async (channel, callback) =>
            {
                if (closed)
                {
                    throw this._cacheError('CACHE_SUBSCRIBER_CLOSED', 'Subscriber handle is closed.');
                }
                if (typeof callback !== 'function')
                {
                    throw this._cacheError('CACHE_INVALID_OPTIONS', 'Subscriber callback must be a function.');
                }
                const physicalChannel = this._physicalChannel(name, channel);
                const channelRegistrations = registrations.get(channel);
                if (channelRegistrations?.has(callback))
                {
                    return handle;
                }
                const wrapper = (message, deliveredChannel) =>
                {
                    try
                    {
                        const callbackResult = callback(this._decodeValue(message),
                            deliveredChannel.startsWith(`${name}:`) ?
                                deliveredChannel.slice(name.length + 1) : deliveredChannel);
                        Promise.resolve(callbackResult).catch(error =>
                            _log.warn(`Redis subscriber '${name}' callback failed: ${error.message}`, MODULE_NAME));
                    }
                    catch (error)
                    {
                        _log.warn(`Redis subscriber '${name}' callback failed: ${error.message}`, MODULE_NAME);
                    }
                };
                await this._withTimeout(subscriber.subscribe(physicalChannel, wrapper),
                    timeoutMs, `SUBSCRIBE '${channel}'`);
                if (!registrations.has(channel))
                {
                    registrations.set(channel, new Map());
                }
                registrations.get(channel).set(callback, wrapper);
                return handle;
            },
            unsubscribe: async (channel, callback) =>
            {
                const channelRegistrations = registrations.get(channel);
                if (!channelRegistrations)
                {
                    return false;
                }
                const physicalChannel = this._physicalChannel(name, channel);
                if (callback)
                {
                    const wrapper = channelRegistrations.get(callback);
                    if (!wrapper)
                    {
                        return false;
                    }
                    await this._withTimeout(subscriber.unsubscribe(physicalChannel, wrapper),
                        timeoutMs, `UNSUBSCRIBE '${channel}'`);
                    channelRegistrations.delete(callback);
                }
                else
                {
                    for (const wrapper of channelRegistrations.values())
                    {
                        await this._withTimeout(subscriber.unsubscribe(physicalChannel, wrapper),
                            timeoutMs, `UNSUBSCRIBE '${channel}'`);
                    }
                    channelRegistrations.clear();
                }
                if (channelRegistrations.size === 0)
                {
                    registrations.delete(channel);
                }
                return true;
            },
            close: () =>
            {
                if (closePromise)
                {
                    return closePromise;
                }
                closed = true;
                closePromise = (async () =>
                {
                    for (const [channel, channelRegistrations] of registrations)
                    {
                        const physicalChannel = this._physicalChannel(name, channel);
                        for (const wrapper of channelRegistrations.values())
                        {
                            await this._withTimeout(subscriber.unsubscribe(physicalChannel, wrapper),
                                timeoutMs, `UNSUBSCRIBE '${channel}'`).catch(() => undefined);
                        }
                    }
                    registrations.clear();
                    context.subscribers.delete(handle);
                    await this._closeRedisClient(subscriber, timeoutMs);
                })();
                return closePromise;
            }
        };
        Object.freeze(handle);
        context.subscribers.add(handle);
        return handle;
    }

    /**
     * @function _destroyRedisClient
     * @memberof mcode.cache
     * @desc Force-destroys a Redis client and removes every event listener.
     * @param {object} client the node-redis client to destroy.
     * @returns {void}
     * @api private
     */
    _destroyRedisClient(client)
    {
        if (!client)
        {
            return;
        }
        try
        {
            if (client.isOpen)
            {
                client.destroy();
            }
        }
        finally
        {
            client.removeAllListeners();
        }
    }

    /**
     * @function _closeRedisClient
     * @memberof mcode.cache
     * @desc Gracefully closes a Redis client within a deadline, then forces cleanup.
     * @param {object} client the node-redis client to close.
     * @param {number} timeoutMs the bounded close timeout.
     * @returns {Promise<void>}
     * @api private
     */
    async _closeRedisClient(client, timeoutMs)
    {
        if (!client)
        {
            return;
        }
        try
        {
            if (client.isOpen)
            {
                await this._withTimeout(client.close(), timeoutMs, 'Redis client close');
            }
        }
        catch (error)
        {
            this._destroyRedisClient(client);
        }
        finally
        {
            client.removeAllListeners();
        }
    }

    /**
     * @function _closeRedisNamespace
     * @memberof mcode.cache
     * @desc Idempotently closes every command, transaction, and subscriber resource.
     * @param {string} name the Redis namespace name.
     * @returns {Promise<void>}
     * @api private
     */
    async _closeRedisNamespace(name)
    {
        const context = this.#redisContexts.get(name);
        if (!context)
        {
            return;
        }
        if (context.closePromise)
        {
            return context.closePromise;
        }

        context.closing = true;
        this._transitionRedisContext(context, cache.REDIS_STATUS.IDLE);
        context.closePromise = (async () =>
        {
            const commandClient = context.client;
            const transactionClients = Array.from(context.transactionClients);
            await Promise.allSettled([
                ...Array.from(context.subscribers).map(subscriber => subscriber.close()),
                ...transactionClients.map(client =>
                    this._closeRedisClient(client, context.config.commandTimeoutMs))
            ]);
            context.transactionClients.clear();
            await this._closeRedisClient(commandClient, context.config.commandTimeoutMs);
            if (this.#redis === commandClient)
            {
                this.#redis = null;
            }
            context.client = null;
            context.connectPromise = null;
            context.lastError = null;
            context.outageLogged = false;
        })().finally(() =>
        {
            context.closing = false;
            context.closePromise = null;
        });

        return context.closePromise;
    }

    // #endregion

    /**
     * @function _withTimeout
     * @api private
     * @memberof mcode.cache
     * @desc Wraps a promise with a timeout to prevent hanging operations.
     * @param {Promise} promise the promise to wrap with timeout.
     * @param {number} timeoutMs the timeout in milliseconds.
     * @param {string} operation the name of the operation for error messages.
     * @returns {Promise} the wrapped promise that will reject if timeout is reached.
     */
    _withTimeout(promise, timeoutMs, operation = 'Cache operation')
    {
        let timeoutId;
        const timeoutPromise = new Promise((_, reject) =>
        {
            timeoutId = setTimeout(() =>
                reject(this._cacheError('CACHE_TIMEOUT', `${operation} timeout after ${timeoutMs}ms`)), timeoutMs);
        });

        return Promise.race([promise, timeoutPromise])
            .finally(() => clearTimeout(timeoutId));
    }

    /**
     * @function _updateNamespaceStatistics
     * @api private
     * @memberof mcode.cache
     * @desc Updates cache statistics for all namespaces.
     * @returns {void}
     */
    _updateNamespaceStatistics()
    {
        for (const namespace of this.#cacheNamespaces)
        {
            try
            {
                if (namespace.type === 'node')
                {
                    // Get keys for this specific namespace
                    const namespaceKeys = this.#cache.keys().filter(key => key.startsWith(`${namespace.name}:`));
                    namespace.keys = namespaceKeys.length;

                    // Calculate sizes for this namespace
                    let ksize = 0;
                    let vsize = 0;

                    for (const key of namespaceKeys)
                    {
                        ksize += Buffer.byteLength(key, 'utf8');
                        const value = this.#cache.get(key);
                        if (value !== undefined)
                        {
                            vsize += Buffer.byteLength(JSON.stringify(value), 'utf8');
                        }
                    }

                    namespace.ksize = ksize;
                    namespace.vsize = vsize;
                }
                else if (namespace.type === 'redis')
                {
                    // For Redis, we can't get stats synchronously, so we'll keep existing values
                    // or set defaults if they don't exist
                    if (namespace.keys === undefined) namespace.keys = 0;
                    if (namespace.ksize === undefined) namespace.ksize = 0;
                    if (namespace.vsize === undefined) namespace.vsize = 0;
                }
            }
            catch (error)
            {
                // If we can't get stats, keep existing values or set defaults
                if (namespace.keys === undefined) namespace.keys = 0;
                if (namespace.ksize === undefined) namespace.ksize = 0;
                if (namespace.vsize === undefined) namespace.vsize = 0;
            }

            // Ensure hits and misses are initialized
            if (namespace.hits === undefined) namespace.hits = 0;
            if (namespace.misses === undefined) namespace.misses = 0;
        }
    }

    /**
     * @function _cacheInit
     * @api private
     * @memberof mcode.cache
     * @desc Initializes the internals of mcode-cache, including the instantiation of the cache client.
     * @returns {status} the cache client connection.
     */
    _cacheInit()
    {
        // if a client already exists, close it and start a new one
        if (this.#cache)
        {
            this.#cache = null;
        }

        if (!this.#cache)
        {
            this.#cache = new NodeCache({
                stdTTL: cache.CACHE_TTL,
                checkperiod: 0  // Disable automatic check period to prevent hanging timers
            });
            _log.done(`mcode-cache initialized with TTL: ${cache.CACHE_TTL} 📣`, MODULE_NAME);
        }
    }

    /**
     * @function _cacheGet
     * @memberof mcode.cache
     * @desc Caches the results of a callback function in cache under the current namespace and returns the key's value.
     * @param {string} cacheKey the key to the cache.
     * @param {function} cb the callback function to get fresh value.
     * @returns {Promise} the cached value.
     */
    async _cacheGet(cacheKey, cb)
    {
        try
        {
            // Extract namespace from cacheKey (format: "namespace:key")
            const namespaceName = cacheKey.split(':')[0];
            const namespaceInfo = this._getNamespaceInfo(namespaceName);

            // if the namespace is not enabled or doesn't exist, just get the data from the callback
            if (!namespaceInfo || !namespaceInfo.enabled)
            {
                // if no callback provided, return undefined
                return cb ? await cb() : undefined;
            }

            let value = this.#cache.get(cacheKey);

            if (value !== undefined)
            {
                // Cache hit - increment hits counter
                namespaceInfo.hits++;
                return value;
            }
            else
            {
                // Cache miss - increment misses counter
                namespaceInfo.misses++;

                // if the key does not exist in cache, use the callback to get the actual data...
                value = cb ? await cb() : undefined;

                // ...and then Set the key:value in the cache
                await this.#cache.set(cacheKey, value);

                return value;
            }
        }
        catch (exp)
        {
            _log.exp(`Exception getting cached '${cacheKey}' key value in NODE cache.`, MODULE_NAME, exp);

            return cb ? await cb() : undefined;  // get the actual data from the data-specific callback function
        }
    }

    /**
     * @function _getLegacyRedisClient
     * @memberof mcode.cache
     * @desc Resolves the ready namespace client for a deprecated physical cache key.
     * @param {string} cacheKey the namespace-prefixed cache key.
     * @returns {Promise<object>} the ready node-redis client.
     * @api private
     */
    async _getLegacyRedisClient(cacheKey)
    {
        const namespaceName = cacheKey.split(':')[0];
        const context = this.#redisContexts.get(namespaceName);
        if (context)
        {
            await this._namespaceReady(namespaceName);
            return context.client;
        }
        if (this.#redis?.isReady)
        {
            return this.#redis;
        }
        throw this._cacheError('CACHE_REDIS_REQUIRED',
            `Redis namespace '${namespaceName}' does not have a ready client.`);
    }

    /**
     * @function _redisGet
     * @memberof mcode.cache
     * @desc Caches the results of a callback function in cache under the current namespace and returns the key's value.
     * @param {string} cacheKey the key to the cache.
     * @param {function} cb the callback function to get fresh value.
     * @returns {Promise} the cached value.
     */
    async _redisGet(cacheKey, cb)
    {
        try
        {
            // Extract namespace from cacheKey (format: "namespace:key")
            const namespaceName = cacheKey.split(':')[0];
            const namespaceInfo = this._getNamespaceInfo(namespaceName);

            // if the namespace is not enabled or doesn't exist, just get the data from the callback
            if (!namespaceInfo || !namespaceInfo.enabled)
            {
                return cb ? await cb() : undefined;
            }

            const client = await this._getLegacyRedisClient(cacheKey);
            let value = await client.get(cacheKey);

            if (value !== null)
            {
                // Cache hit - increment hits counter
                namespaceInfo.hits++;
                return value;
            }
            else
            {
                // Cache miss - increment misses counter
                namespaceInfo.misses++;

                // if the key does not exist in cache, use the callback to get the actual data...
                value = cb ? await cb() : undefined;

                // ...and then Set the key:value in the cache
                if (value !== undefined)
                {
                    await client.set(cacheKey, value);
                }

                return value;
            }
        }
        catch (exp)
        {
            _log.exp(`Exception getting cached '${cacheKey}' key value in REDIS cache.`, MODULE_NAME, exp);

            return cb ? await cb() : undefined;
        }
    }

    /**
     * @function _cacheSet
     * @memberof mcode.cache
     * @desc Sets a key value in the cache.
     * @param {string} cacheKey the cache key to be set.
     * @param {string} value the value to be set in the cache.
     * @returns {Promise<void>}
     */
    async _cacheSet(cacheKey, value)
    {
        try
        {
            // Extract namespace from cacheKey (format: "namespace:key")
            const namespaceName = cacheKey.split(':')[0];
            const namespaceInfo = this._getNamespaceInfo(namespaceName);

            // if the namespace is not enabled or doesn't exist, just return
            if (!namespaceInfo || !namespaceInfo.enabled)
            {
                return;
            }

            await this.#cache.set(cacheKey, value);
        }
        catch (exp)
        {
            _log.exp(`Exception setting ${cacheKey} value in NODE cache.`, MODULE_NAME, exp);
        }
    }

    /**
     * @function _redisSet
     * @memberof mcode.cache
     * @desc Sets a key value in the cache.
     * @param {string} cacheKey the cache key to be set.
     * @param {string} value the value to be set in the cache.
     * @returns {Promise<void>}
     */
    async _redisSet(cacheKey, value)
    {
        try
        {
            // Extract namespace from cacheKey (format: "namespace:key")
            const namespaceName = cacheKey.split(':')[0];
            const namespaceInfo = this._getNamespaceInfo(namespaceName);

            // if the namespace is not enabled or doesn't exist, just return
            if (!namespaceInfo || !namespaceInfo.enabled)
            {
                return;
            }

            const client = await this._getLegacyRedisClient(cacheKey);
            await client.set(cacheKey, value);
        }
        catch (exp)
        {
            _log.exp(`Exception setting ${cacheKey} value in REDIS cache.`, MODULE_NAME, exp);
        }
    }

    /**
     * @function _cacheDrop
     * @memberof mcode.cache
     * @desc Drops a key value from the cache based on the 'key' name.
     * @param {string} cacheKey the cache key to be droppped.
     * @returns {number} the number of keys deleted from the cache.
     * @api public
     * @example
     *     const count = await mcode.cacheDrop(keyName);
     */
    async _cacheDrop(cacheKey)
    {
        return await this.#cache.del(cacheKey);
    }

    /**
     * @function _redisDrop
     * @memberof mcode.cache
     * @desc Drops a key value from the cache based on the 'key' name.
     * @param {string} cacheKey the cache key to be droppped.
     * @returns {number} the number of keys deleted from the cache.
     * @api public
     * @example
     *     const count = await mcode.cacheDrop(keyName);
     */
    async _redisDrop(cacheKey)
    {
        const client = await this._getLegacyRedisClient(cacheKey);
        return await client.del(cacheKey);
    }

    /**
     * @function _cacheKeys
     * @memberof mcode.cache
     * @desc returns a filtered list of keys in the cache,
     * NOTE: keys() in node-cache does not support wildcards.
     * @param {string} pattern the key pattern to list all keys from.
     * @returns {number} the number of keys deleted from the cache.
     * @api public
     * @example
     *     const count = await mcode.cacheDrop(keyName);
     */
    async _cacheKeys(pattern)
    {
        const allKeys = this.#cache.keys(); // Get all keys from node-cache
        const regexPattern = this._convertGlobToRegExp(pattern); // Convert glob pattern to RegExp
        return allKeys.filter(key => regexPattern.test(key)); // Filter keys based on the Regex
    }

    /**
     * @function _convertGlobToRegExp
     * @memberof mcode.cache
     * @desc Converts a Redis-compatible glob pattern to an anchored regular expression.
     * @param {string} globPattern the Redis-compatible glob pattern.
     * @returns {RegExp} the equivalent anchored regular expression.
     * @api private
     */
    _convertGlobToRegExp(globPattern)
    {
        const escapedPattern = globPattern
            .replace(/\*/g, '.*')  // Replace * with .* (matches any characters)
            .replace(/\?/g, '.')   // Replace ? with . (matches any single character)
            .replace(/\[/g, '\\[') // Escape [
            .replace(/\]/g, '\\]'); // Escape ]

        return new RegExp(`^${escapedPattern}$`); // Create a RegExp from the glob pattern
    }

    /**
     * @function _listKeys
     * @memberof mcode.cache
     * @desc Common helper method to process cache keys and create the result objects with type and value preview.
     * @param {Array} cacheKeys array of cache keys to process.
     * @param {string} namespace the namespace these keys belong to.
     * @param {string} cacheType the type of cache ('node' or 'redis').
     * @returns {Array} array of processed key objects.
     * @api private
     */
    async _listKeys(cacheKeys, namespace, cacheType)
    {
        const keyArray = [];

        // Process each key individually to get proper type and value preview
        for (const fullKey of cacheKeys)
        {
            try
            {
                // Add timeout protection for individual key retrieval
                const getValuePromise = cacheType === 'redis' ?
                    this._redisGet(fullKey) :
                    this._cacheGet(fullKey);
                const keyValue = await this._withTimeout(getValuePromise, 3000, 'Key retrieval');
                const {type, preview} = this._getTypeAndPreview(keyValue);

                keyArray.push({
                    namespace: namespace,
                    key: fullKey.replace(`${namespace}:`, ''),
                    cache: cacheType,
                    type: type,
                    preview: preview
                });
            }
            catch (error)
            {
                // Handle case where key might not exist, be accessible, or timeout
                keyArray.push({
                    namespace: namespace,
                    key: fullKey.replace(`${namespace}:`, ''),
                    cache: cacheType,
                    type: null,
                    preview: error.message.includes('timeout') ?
                        '&lt;Key retrieval timeout&gt;' :
                        '&lt;Value is undefined in cache&gt;'
                });
            }
        }

        return keyArray;
    }

    /**
     * @function _getTypeAndPreview
     * @memberof mcode.cache
     * @desc Determines the type and creates a preview for any JSON-compatible data type.
     * For arrays and objects with JSON string representation < 128 bytes, returns the actual object
     * to allow UI/UX code to handle display formatting. Otherwise returns HTML-escaped string.
     * @param {any} value the value to analyze.
     * @returns {object} object containing type and preview properties.
     * @api private
     */
    _getTypeAndPreview(value)
    {
        // Handle null explicitly (typeof null === 'object')
        if (value === null)
        {
            return {
                type: 'null',
                preview: null
            };
        }

        // Handle undefined
        if (value === undefined)
        {
            return {
                type: 'undefined',
                preview: undefined
            };
        }

        const valueType = typeof value;

        switch (valueType)
        {
            case 'string':
                {
                    const escapedString = this._escapeHtml(value);
                    const preview = escapedString.length > 50
                        ? escapedString.substring(0, 47) + '...'
                        : escapedString;
                    return {
                        type: 'string',
                        preview: preview
                    };
                }

            case 'number':
                return {
                    type: Number.isInteger(value) ? 'integer' : 'number',
                    preview: value
                };

            case 'boolean':
                return {
                    type: 'boolean',
                    preview: value
                };

            case 'object':
                {
                    // Handle arrays - if small just return it as a preview
                    if (Array.isArray(value))
                    {
                        const length = value.length;
                        const jsonString = JSON.stringify(value);
                        const jsonByteLength = Buffer.byteLength(jsonString, 'utf8');

                        return {
                            type: `array[${length}]`,
                            preview: jsonByteLength < 128 ? value : this._escapeHtml(jsonString)
                        };
                    }

                    // Handle objects - if small just return it as a preview
                    const keyCount = Object.keys(value).length;
                    const jsonString = JSON.stringify(value);
                    const jsonByteLength = Buffer.byteLength(jsonString, 'utf8');

                    return {
                        type: `object[${keyCount}]`,
                        preview: jsonByteLength < 128 ? value : this._escapeHtml(jsonString)
                    };
                }

            case 'function':
                {
                    const funcStr = value.toString();
                    const funcName = value.name || 'anonymous';
                    let preview = `function ${funcName}()`;

                    // Try to extract parameter list
                    const paramMatch = funcStr.match(/function[^(]*\(([^)]*)\)/);
                    if (paramMatch)
                    {
                        const params = paramMatch[1].trim();
                        preview = params
                            ? `function ${funcName}(${params})`
                            : `function ${funcName}()`;
                    }

                    return {
                        type: 'function',
                        preview: this._escapeHtml(preview)
                    };
                }

            case 'symbol':
                return {
                    type: 'symbol',
                    preview: this._escapeHtml(value.toString())
                };

            case 'bigint':
                return {
                    type: 'bigint',
                    preview: value
                };

            default:
                // Fallback for any unknown types
                return {
                    type: valueType,
                    preview: this._escapeHtml(String(value))
                };
        }
    }

    /**
     * @function _escapeHtml
     * @memberof mcode.cache
     * @desc Escapes HTML characters to prevent rendering issues in web display.
     * @param {string} text the text to escape.
     * @returns {string} the escaped text.
     * @api private
     */
    _escapeHtml(text)
    {
        const htmlEscapeMap = {
            '&': '&amp;',
            '<': '&lt;',
            '>': '&gt;',
            '"': '&quot;',
            "'": '&#x27;',
            '/': '&#x2F;'
        };

        return String(text).replace(/[&<>"'/]/g, (match) => htmlEscapeMap[match]);
    }

    // #endregion
}

// #endregion

// #region  E X P O R T S

// Export the Singleton instance
const instance = new cache();

Object.freeze(instance);

// Automatically export all public methods and properties...

// Export all the Public METHODs (excluding the constructor)
Object.getOwnPropertyNames(Object.getPrototypeOf(instance)).forEach((method) =>
{
    if (method !== 'constructor' && typeof instance[method] === 'function' && !method.startsWith('_'))
    {
        // Bind the method to the instance if it is a function and does not start with '_' (Private)
        module.exports[method] = instance[method].bind(instance);
    }
});

// Export all the Public PROPERTYs (get/set)
const descriptors = Object.getOwnPropertyDescriptors(Object.getPrototypeOf(instance));
for (const [key, descriptor] of Object.entries(descriptors))
{
    if (!key.startsWith('_') && (descriptor.get || descriptor.set))
    {
        Object.defineProperty(module.exports, key, {
            get: descriptor.get ? descriptor.get.bind(instance) : undefined,
            set: descriptor.set ? descriptor.set.bind(instance) : undefined,
            enumerable: true,  // Ensure the property is enumerable
            configurable: true,
        });
    }
}

// #endregion
// #endregion