Class: cache

cache() → {cache}

cache Class to provide transparent data caching for MicroCODE applications.

Constructor

new cache() → {cache}

Creates or returns the singleton cache instance.
Source:
Returns:
the singleton cache instance.
Type
cache

Members

cacheErrors

Properties:
Name Type Description
cacheErrors object the frozen stable package error codes for operational branching.
Source:

cacheNamespace

Properties:
Name Type Description
cacheNamespace string 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().
Source:

cacheNamespaces

Properties:
Name Type Description
cacheNamespaces array 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.
Source:

cacheReady

Properties:
Name Type Description
cacheReady boolean whether the cache instance and configured Redis namespaces are ready.
Source:

cacheTTL

Properties:
Name Type Description
cacheTTL number the cache Time-To-Live property, in seconds.
Source:

redisMinimumVersion

Properties:
Name Type Description
redisMinimumVersion string the minimum supported Redis server version.
Source:

redisPassword

Properties:
Name Type Description
redisPassword string the Password to the Redis Server.
Source:

redisPort

Properties:
Name Type Description
redisPort string the PORT to the Redis Server.
Source:

redisStatus

Properties:
Name Type Description
redisStatus object the frozen stable Redis namespace status constants.
Source:

redisURL

Properties:
Name Type Description
redisURL string the URL to the Redis Server.
Source:

redisUser

Properties:
Name Type Description
redisUser string the User to the Redis Server.
Source:

(static) cache#cacheNamespace

Sets the default namespace for subsequent singleton cache operations.
Properties:
Name Type Description
cacheNamespace
Source:

(static) cache#cacheTTL

Sets the default cache Time-To-Live in seconds.
Properties:
Name Type Description
cacheTTL
Source:

(static) cache#redisPassword

Sets the legacy Redis password.
Properties:
Name Type Description
redisPassword
Source:

(static) cache#redisPort

Sets the legacy Redis server port.
Properties:
Name Type Description
redisPort
Source:

(static) cache#redisURL

Sets the legacy Redis server URL.
Properties:
Name Type Description
redisURL
Source:

(static) cache#redisUser

Sets the legacy Redis username.
Properties:
Name Type Description
redisUser
Source:

Methods

(static) _appendMultiOperation(name, multi, operation) → {function}

Validates and appends one typed operation to a node-redis MULTI.
Parameters:
Name Type Description
name string the Redis namespace name.
multi object the node-redis MULTI builder.
operation object the queued typed operation.
Source:
Returns:
the reply transformation function.
Type
function

(static) _assertTransactionReplies(replies, operation) → {Array.<object>}

Throws the first normalized transaction command error.
Parameters:
Name Type Description
replies Array.<object> the normalized transaction replies.
operation string the transaction operation name.
Source:
Returns:
the successful replies.
Type
Array.<object>

(static) _attachRedisClientListeners(context, client) → {void}

Attaches guarded lifecycle and required error listeners to a Redis client.
Parameters:
Name Type Description
context object the Redis namespace context.
client object the node-redis client.
Source:
Returns:
Type
void

(static) _buildRedisClientOptions(config) → {object}

Maps explicit namespace policy to node-redis client options.
Parameters:
Name Type Description
config object the normalized Redis namespace configuration.
Source:
Returns:
the node-redis client options.
Type
object

(static) _buildSetOptions(options) → {object}

Validates package SET options and maps them to native Redis modifiers.
Parameters:
Name Type Description
options object the package cacheSet options.
Source:
Returns:
the node-redis SET options.
Type
object

(static) _buildSortedSetOptions(options) → {object}

Maps package sorted-set conditions to native Redis modifiers.
Parameters:
Name Type Description
options object the sortedSetAdd options.
Source:
Returns:
the node-redis ZADD options.
Type
object

(static) _cacheDrop(cacheKey) → {number}

Drops a key value from the cache based on the 'key' name.
Parameters:
Name Type Description
cacheKey string the cache key to be droppped.
Source:
Returns:
the number of keys deleted from the cache.
Type
number
Example
const count = await mcode.cacheDrop(keyName);

(static) _cacheError(code, message, cause) → {Error}

Creates an Error with a stable package error code and optional cause.
Parameters:
Name Type Description
code string the stable package error code.
message string the human-readable error message.
cause Error the optional underlying error.
Source:
Returns:
the coded cache error.
Type
Error

(static) _cacheGet(cacheKey, cb) → {Promise}

Caches the results of a callback function in cache under the current namespace and returns the key's value.
Parameters:
Name Type Description
cacheKey string the key to the cache.
cb function the callback function to get fresh value.
Source:
Returns:
the cached value.
Type
Promise

(static) _cacheInit() → {status}

Initializes the internals of mcode-cache, including the instantiation of the cache client.
Source:
Returns:
the cache client connection.
Type
status

(static) _cacheKeys(pattern) → {number}

returns a filtered list of keys in the cache, NOTE: keys() in node-cache does not support wildcards.
Parameters:
Name Type Description
pattern string the key pattern to list all keys from.
Source:
Returns:
the number of keys deleted from the cache.
Type
number
Example
const count = await mcode.cacheDrop(keyName);

(static) _cacheSet(cacheKey, value) → {Promise.<void>}

Sets a key value in the cache.
Parameters:
Name Type Description
cacheKey string the cache key to be set.
value string the value to be set in the cache.
Source:
Returns:
Type
Promise.<void>

(static) _canonicalize(value, seen) → {*}

Recursively validates and key-sorts a supported typed cache value.
Parameters:
Name Type Description
value * the value to canonicalize.
seen Set the object references in the current recursion path.
Source:
Returns:
the canonical JSON-compatible value.
Type
*

(static) _closeRedisClient(client, timeoutMs) → {Promise.<void>}

Gracefully closes a Redis client within a deadline, then forces cleanup.
Parameters:
Name Type Description
client object the node-redis client to close.
timeoutMs number the bounded close timeout.
Source:
Returns:
Type
Promise.<void>

(static) _closeRedisNamespace(name) → {Promise.<void>}

Idempotently closes every command, transaction, and subscriber resource.
Parameters:
Name Type Description
name string the Redis namespace name.
Source:
Returns:
Type
Promise.<void>

(static) _compareVersions(left, right) → {number}

Compares the first three numeric components of two server versions.
Parameters:
Name Type Description
left string the reported server version.
right string the minimum required server version.
Source:
Returns:
-1, 0, or 1 for less than, equal, or greater than.
Type
number

(static) _connectRedisContext(context) → {Promise.<object>}

Creates, connects, and capability-gates a namespace command client.
Parameters:
Name Type Description
context object the Redis namespace context.
Source:
Returns:
the ready node-redis client.
Type
Promise.<object>

(static) _convertGlobToRegExp(globPattern) → {RegExp}

Converts a Redis-compatible glob pattern to an anchored regular expression.
Parameters:
Name Type Description
globPattern string the Redis-compatible glob pattern.
Source:
Returns:
the equivalent anchored regular expression.
Type
RegExp

(static) _createMultiBuilder(name, client, deferred) → {object}

Creates a typed transaction builder without exposing raw Redis commands.
Parameters:
Name Type Description
name string the Redis namespace name.
client object the optional exclusive Redis client.
deferred boolean whether WATCH owns transaction execution.
Source:
Returns:
the frozen typed transaction builder.
Type
object

(static) _createNamespaceHandle(name) → {object}

Creates or returns the immutable scoped handle for a namespace.
Parameters:
Name Type Description
name string the registered namespace name.
Source:
Returns:
the immutable namespace handle.
Type
object

(static) _createRedisContext(config) → {object}

Creates the private lifecycle state for one Redis namespace.
Parameters:
Name Type Description
config object the normalized Redis namespace configuration.
Source:
Returns:
the mutable private Redis context.
Type
object

(static) _createSubscriber(name, options) → {Promise.<object>}

Creates an isolated, tracked, and immutable subscriber handle.
Parameters:
Name Type Description
name string the Redis namespace name.
options object the bounded subscriber readiness options.
Source:
Returns:
the immutable subscriber handle.
Type
Promise.<object>

(static) _decodeValue(value) → {*}

Decodes a versioned cache value while preserving missing-value semantics.
Parameters:
Name Type Description
value string | null | undefined the stored Redis value.
Source:
Returns:
the decoded value, or undefined when missing.
Type
*

(static) _destroyRedisClient(client) → {void}

Force-destroys a Redis client and removes every event listener.
Parameters:
Name Type Description
client object the node-redis client to destroy.
Source:
Returns:
Type
void

(static) _encodeValue(value) → {string}

Encodes a supported value with the versioned canonical cache codec.
Parameters:
Name Type Description
value * the value to encode.
Source:
Returns:
the versioned encoded Redis value.
Type
string

(static) _ensureGeneration(name, options) → {Promise.<object>}

Checks whether a namespace has the requested ready generation marker.
Parameters:
Name Type Description
name string the Redis namespace name.
options object the generation marker options.
Source:
Returns:
the current flag and stored marker.
Type
Promise.<object>

(static) _escapeHtml(text) → {string}

Escapes HTML characters to prevent rendering issues in web display.
Parameters:
Name Type Description
text string the text to escape.
Source:
Returns:
the escaped text.
Type
string

(static) _executeMultiOperations(name, operations, client) → {Promise.<Array.<object>>}

Executes typed MULTI operations and normalizes every command reply.
Parameters:
Name Type Description
name string the Redis namespace name.
operations Array.<object> the queued typed operations.
client object the optional exclusive Redis client.
Source:
Returns:
the normalized result/error envelopes.
Type
Promise.<Array.<object>>

(static) _executeRedis(name, operation, task, mutation, timeoutMs) → {Promise.<*>}

Executes one Redis task with readiness, deadline, and ambiguity handling.
Parameters:
Name Type Description
name string the Redis namespace name.
operation string the operation name used in errors.
task function the function receiving the ready command client.
mutation boolean whether a post-dispatch timeout is outcome-unknown.
timeoutMs number the optional operation timeout override.
Source:
Returns:
the Redis operation result.
Type
Promise.<*>

(static) _getLegacyRedisClient(cacheKey) → {Promise.<object>}

Resolves the ready namespace client for a deprecated physical cache key.
Parameters:
Name Type Description
cacheKey string the namespace-prefixed cache key.
Source:
Returns:
the ready node-redis client.
Type
Promise.<object>

(static) _getNamespaceInfo(namespaceName) → {object|null}

Gets namespace information by name.
Parameters:
Name Type Description
namespaceName string the name of the namespace to find.
Source:
Returns:
the namespace object or null if not found.
Type
object | null

(static) _getTypeAndPreview(value) → {object}

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.
Parameters:
Name Type Description
value any the value to analyze.
Source:
Returns:
object containing type and preview properties.
Type
object

(static) _legacyRedisScanKeys(name, pattern, limit) → {Promise.<Array.<string>>}

Collects bounded physical keys for deprecated singleton operations.
Parameters:
Name Type Description
name string the Redis namespace name.
pattern string the logical key pattern.
limit number the maximum number of keys to collect.
Source:
Returns:
the bounded physical Redis keys.
Type
Promise.<Array.<string>>

(static) _listKeys(cacheKeys, namespace, cacheType) → {Array}

Common helper method to process cache keys and create the result objects with type and value preview.
Parameters:
Name Type Description
cacheKeys Array array of cache keys to process.
namespace string the namespace these keys belong to.
cacheType string the type of cache ('node' or 'redis').
Source:
Returns:
array of processed key objects.
Type
Array

(static) _namespaceCacheDrop(name, keyOrKeys, client) → {Promise.<number>}

Deletes one or more scoped logical keys.
Parameters:
Name Type Description
name string the namespace name.
keyOrKeys string | Array.<string> the logical key or keys.
client object the optional exclusive Redis client.
Source:
Returns:
the number of deleted keys.
Type
Promise.<number>

(static) _namespaceCacheDropIfEqual(name, key, expectedValue, client) → {Promise.<boolean>}

Deletes one scoped key only when its encoded value matches.
Parameters:
Name Type Description
name string the namespace name.
key string the logical key.
expectedValue * the expected typed value.
client object the optional exclusive Redis client.
Source:
Returns:
true when the key was deleted.
Type
Promise.<boolean>

(static) _namespaceCacheExists(name, key, client) → {Promise.<boolean>}

Checks whether one scoped logical key exists.
Parameters:
Name Type Description
name string the namespace name.
key string the logical key.
client object the optional exclusive Redis client.
Source:
Returns:
true when the key exists.
Type
Promise.<boolean>

(static) _namespaceCacheExpire(name, key, options, client) → {Promise.<boolean>}

Applies an explicit seconds or milliseconds expiry to a scoped key.
Parameters:
Name Type Description
name string the namespace name.
key string the logical key.
options object the explicit expiry options.
client object the optional exclusive Redis client.
Source:
Returns:
true when expiry was applied.
Type
Promise.<boolean>

(static) _namespaceCacheGet(name, key, client) → {Promise.<*>}

Gets and decodes one logical key while updating namespace statistics.
Parameters:
Name Type Description
name string the namespace name.
key string the logical key.
client object the optional exclusive Redis client.
Source:
Returns:
the cached value, or undefined when missing.
Type
Promise.<*>

(static) _namespaceCacheGetMany(name, keys, client) → {Promise.<Array>}

Gets and decodes multiple ordered logical keys.
Parameters:
Name Type Description
name string the namespace name.
keys Array.<string> the logical keys.
client object the optional exclusive Redis client.
Source:
Returns:
the ordered cached values.
Type
Promise.<Array>

(static) _namespaceCacheSet(name, key, value, options, client, timeoutMs) → {Promise.<boolean>}

Canonically sets a scoped value with optional native conditions and expiry.
Parameters:
Name Type Description
name string the namespace name.
key string the logical key.
value * the supported typed value.
options object the package SET options.
client object the optional exclusive Redis client.
timeoutMs number the optional operation timeout override.
Source:
Returns:
true when the value was set.
Type
Promise.<boolean>

(static) _namespaceCacheTTL(name, key, milliseconds, client) → {Promise.<number>}

Reads a scoped key TTL in seconds or milliseconds.
Parameters:
Name Type Description
name string the namespace name.
key string the logical key.
milliseconds boolean whether to return PTTL milliseconds.
client object the optional exclusive Redis client.
Source:
Returns:
the Redis-compatible TTL result.
Type
Promise.<number>

(static) _namespaceGeoAdd(name, key, members, client) → {Promise.<number>}

Adds one or more members to a scoped geo index.
Parameters:
Name Type Description
name string the Redis namespace name.
key string the logical geo key.
members object | Array.<object> the geo members.
client object the optional exclusive Redis client.
Source:
Returns:
the number of added members.
Type
Promise.<number>

(static) _namespaceGeoRemove(name, key, members, client) → {Promise.<number>}

Removes one or more members from a scoped geo index.
Parameters:
Name Type Description
name string the Redis namespace name.
key string the logical geo key.
members string | Array.<string> the members to remove.
client object the optional exclusive Redis client.
Source:
Returns:
the number of removed members.
Type
Promise.<number>

(static) _namespaceGeoSearch(name, key, options) → {Promise.<Array.<string>>}

Searches a scoped geo index by member, radius, or box.
Parameters:
Name Type Description
name string the Redis namespace name.
key string the logical geo key.
options object the bounded geo search options.
Source:
Returns:
the matching members.
Type
Promise.<Array.<string>>

(static) _namespaceInfo(name, section) → {Promise.<string>}

Reads an allowlisted Redis INFO section.
Parameters:
Name Type Description
name string the Redis namespace name.
section string the allowlisted INFO section.
Source:
Returns:
the Redis INFO response.
Type
Promise.<string>

(static) _namespaceInspect(name, options) → {Promise.<object>}

Inspects bounded scoped keys with type and optional string value.
Parameters:
Name Type Description
name string the Redis namespace name.
options object the bounded inspection options.
Source:
Returns:
the next cursor and inspected entries.
Type
Promise.<object>

(static) _namespacePing(name) → {Promise.<string>}

Pings the Redis server for a namespace.
Parameters:
Name Type Description
name string the Redis namespace name.
Source:
Returns:
the Redis PING reply.
Type
Promise.<string>

(static) _namespacePublish(name, channel, value) → {Promise.<number>}

Publishes one encoded typed value on a scoped Redis channel.
Parameters:
Name Type Description
name string the Redis namespace name.
channel string the logical channel.
value * the supported typed message value.
Source:
Returns:
the number of receiving subscribers.
Type
Promise.<number>

(static) _namespaceReady(name, options) → {Promise.<object>}

Waits within a deadline for a namespace handle to become ready.
Parameters:
Name Type Description
name string the registered namespace name.
options object the bounded readiness options.
Source:
Returns:
the immutable ready namespace handle.
Type
Promise.<object>

(static) _namespaceScan(name, options) → {Promise.<object>}

Reads one bounded SCAN page and strips the namespace prefix.
Parameters:
Name Type Description
name string the Redis namespace name.
options object the cursor, pattern, and count options.
Source:
Returns:
the next cursor and logical keys.
Type
Promise.<object>

(static) _namespaceSortedSetAdd(name, key, members, options, client) → {Promise.<number>}

Adds scored members to a scoped sorted set.
Parameters:
Name Type Description
name string the Redis namespace name.
key string the logical sorted-set key.
members object | Array.<object> the scored members.
options object the package ZADD options.
client object the optional exclusive Redis client.
Source:
Returns:
the Redis ZADD result.
Type
Promise.<number>

(static) _namespaceSortedSetRange(name, key, options) → {Promise.<Array>}

Reads an index range from a scoped sorted set.
Parameters:
Name Type Description
name string the Redis namespace name.
key string the logical sorted-set key.
options object the range, reverse, and score-return options.
Source:
Returns:
the members or member-score objects.
Type
Promise.<Array>

(static) _namespaceSortedSetRangeByScore(name, key, options) → {Promise.<Array>}

Reads a bounded score range from a scoped sorted set.
Parameters:
Name Type Description
name string the Redis namespace name.
key string the logical sorted-set key.
options object the score bounds, limit, and score-return options.
Source:
Returns:
the members or member-score objects.
Type
Promise.<Array>

(static) _namespaceSortedSetRank(name, key, member, reverse) → {Promise.<(number|null)>}

Reads the forward or reverse rank of a scoped sorted-set member.
Parameters:
Name Type Description
name string the Redis namespace name.
key string the logical sorted-set key.
member string the member to rank.
reverse boolean whether to use reverse rank.
Source:
Returns:
the member rank, or null when missing.
Type
Promise.<(number|null)>

(static) _namespaceSortedSetRemove(name, key, members, client) → {Promise.<number>}

Removes members from a scoped sorted set.
Parameters:
Name Type Description
name string the Redis namespace name.
key string the logical sorted-set key.
members string | Array.<string> the members to remove.
client object the optional exclusive Redis client.
Source:
Returns:
the number of removed members.
Type
Promise.<number>

(static) _namespaceSortedSetScore(name, key, member) → {Promise.<(number|null)>}

Reads the score of a scoped sorted-set member.
Parameters:
Name Type Description
name string the Redis namespace name.
key string the logical sorted-set key.
member string the member to read.
Source:
Returns:
the member score, or null when missing.
Type
Promise.<(number|null)>

(static) _namespaceTime(name) → {Promise.<object>}

Reads Redis server time as numeric seconds and microseconds.
Parameters:
Name Type Description
name string the Redis namespace name.
Source:
Returns:
the numeric Redis server time.
Type
Promise.<object>

(static) _normalizeGeoMembers(members) → {Array.<object>}

Validates and normalizes one or more geo members.
Parameters:
Name Type Description
members object | Array.<object> the geo members to normalize.
Source:
Returns:
the normalized geo members.
Type
Array.<object>

(static) _normalizeNamespaceConfig(namespace) → {object}

Validates and freezes an explicit node or Redis namespace configuration.
Parameters:
Name Type Description
namespace object the namespace configuration to normalize.
Source:
Returns:
the normalized namespace configuration.
Type
object

(static) _normalizeSortedSetMembers(members) → {Array.<object>}

Validates and normalizes one or more sorted-set members.
Parameters:
Name Type Description
members object | Array.<object> the scored members to normalize.
Source:
Returns:
the normalized node-redis members.
Type
Array.<object>

(static) _physicalChannel(namespaceName, logicalChannel) → {string}

Builds a namespace-owned Redis channel from a validated logical channel.
Parameters:
Name Type Description
namespaceName string the namespace that owns the channel.
logicalChannel string the unprefixed logical channel.
Source:
Returns:
the physical Redis channel.
Type
string

(static) _physicalKey(namespaceName, logicalKey) → {string}

Builds a namespace-owned Redis key from a validated logical key.
Parameters:
Name Type Description
namespaceName string the namespace that owns the key.
logicalKey string the unprefixed logical key.
Source:
Returns:
the physical Redis key.
Type
string

(static) _redisConfigSignature(config) → {string}

Creates the stable comparison signature for Redis namespace idempotence.
Parameters:
Name Type Description
config object the normalized Redis namespace configuration.
Source:
Returns:
the serialized non-function configuration signature.
Type
string

(static) _redisDrop(cacheKey) → {number}

Drops a key value from the cache based on the 'key' name.
Parameters:
Name Type Description
cacheKey string the cache key to be droppped.
Source:
Returns:
the number of keys deleted from the cache.
Type
number
Example
const count = await mcode.cacheDrop(keyName);

(static) _redisGet(cacheKey, cb) → {Promise}

Caches the results of a callback function in cache under the current namespace and returns the key's value.
Parameters:
Name Type Description
cacheKey string the key to the cache.
cb function the callback function to get fresh value.
Source:
Returns:
the cached value.
Type
Promise

(static) _redisSet(cacheKey, value) → {Promise.<void>}

Sets a key value in the cache.
Parameters:
Name Type Description
cacheKey string the cache key to be set.
value string the value to be set in the cache.
Source:
Returns:
Type
Promise.<void>

(static) _remainingDeadline(expiresAt, operation) → {number}

Calculates remaining bounded operation time and rejects expired work.
Parameters:
Name Type Description
expiresAt number the absolute deadline in epoch milliseconds.
operation string the operation name used in errors.
Source:
Returns:
the remaining deadline in milliseconds.
Type
number

(static) _resetGeneration(name, options) → {Promise.<object>}

Performs a guarded, bounded, atomic, and verified namespace reset.
Parameters:
Name Type Description
name string the Redis namespace name.
options object the explicit guard, generation, limit, and deadline options.
Source:
Returns:
the reset status, generation, and deleted-key count.
Type
Promise.<object>

(static) _transitionRedisContext(context, status, error) → {void}

Applies a deduplicated Redis lifecycle transition and outage log state.
Parameters:
Name Type Description
context object the Redis namespace context.
status string the stable package status value.
error Error the optional transition error.
Source:
Returns:
Type
void

(static) _updateNamespaceStatistics() → {void}

Updates cache statistics for all namespaces.
Source:
Returns:
Type
void

(static) _validateGenerationOptions(options) → {object}

Validates generation marker identity options shared by ensure and reset.
Parameters:
Name Type Description
options object the generation options.
Source:
Returns:
the validated generation options.
Type
object

(static) _validateLogicalName(value, kind) → {string}

Validates a logical key or channel without a namespace prefix.
Parameters:
Name Type Description
value string the logical name to validate.
kind string the logical-name kind, either key or channel.
Source:
Returns:
the validated logical name.
Type
string

(static) _validateMember(member) → {string}

Validates a geo or sorted-set member string.
Parameters:
Name Type Description
member string the member to validate.
Source:
Returns:
the validated member.
Type
string

(static) _validateNamespaceName(name) → {string}

Validates a namespace name against the scoped cache contract.
Parameters:
Name Type Description
name string the namespace name to validate.
Source:
Returns:
the validated namespace name.
Type
string

(static) _validateOptionsObject(options, operation) → {object}

Requires an operation's options value to be a non-array object.
Parameters:
Name Type Description
options object the options value to validate.
operation string the operation name used in errors.
Source:
Returns:
the validated options object.
Type
object

(static) _validatePositiveInteger(value, name) → {void}

Requires a configuration value to be a positive safe integer.
Parameters:
Name Type Description
value number the numeric value to validate.
name string the configuration field name.
Source:
Returns:
Type
void

(static) _validateScanPattern(name, pattern) → {string}

Validates a bounded logical SCAN pattern and rejects physical prefixes.
Parameters:
Name Type Description
name string the namespace name.
pattern string the logical SCAN pattern.
Source:
Returns:
the validated logical pattern.
Type
string

(static) _verifyRedisCapabilities(client, config) → {Promise.<void>}

Verifies PING, Redis version, DELEX support, and standalone mode.
Parameters:
Name Type Description
client object the connected node-redis client.
config object the normalized Redis namespace configuration.
Source:
Returns:
Type
Promise.<void>

(static) _watchTransaction(name, options, planner) → {Promise.<Array.<object>>}

Executes a bounded optimistic transaction on an exclusive connection.
Parameters:
Name Type Description
name string the Redis namespace name.
options object the watched keys, retry, and deadline options.
planner function the side-effect-free transaction planner.
Source:
Returns:
the normalized EXEC replies.
Type
Promise.<Array.<object>>

(static) _withTimeout(promise, timeoutMs, operation) → {Promise}

Wraps a promise with a timeout to prevent hanging operations.
Parameters:
Name Type Description
promise Promise the promise to wrap with timeout.
timeoutMs number the timeout in milliseconds.
operation string the name of the operation for error messages.
Source:
Returns:
the wrapped promise that will reject if timeout is reached.
Type
Promise

(static) addNamespace(namespace) → {object}

Adds a new namespace to the cache server.
Parameters:
Name Type Description
namespace object the namespace and configuration to be added to the cache server.
Source:
Returns:
the immutable namespace handle.
Type
object
Example
const namespace = {name: 'MicroCODE', type: 'node', user: 'username', password: '...'};

(static) cacheDrop(key) → {number}

Drops a key value from the cache based on the 'key' name.
Parameters:
Name Type Description
key string the app key to be droppped.
Source:
Returns:
the number of keys deleted from the cache.
Type
number
Example
const count = await mcode.cacheDrop(keyName);

(static) cacheDropAll(cache, namespace, pattern) → {number}

Drops all keys from the cache based on the App's namespace.
Parameters:
Name Type Description
cache string the cache to drop all keys from.
namespace string the namespace to drop all keys from.
pattern string the key pattern to drop all keys from.
Source:
Returns:
the number of keys deleted from the cache.
Type
number
Example
const result = await mcode.cacheDropAll();
   const result = await mcode.cacheDropAll({cache: 'redis', namespace: 'GM-GPS-eMITS-DB', pattern: '*'});

(static) cacheEnabled(cacheName) → {boolean}

Checks if caching is enabled for a specific namespace.
Parameters:
Name Type Description
cacheName string the name of the cache namespace to check.
Source:
Returns:
true if caching is enabled for the namespace, false otherwise.
Type
boolean
Example
const isEnabled = mcode.cacheEnabled('MicroCODE');

(static) cacheGet(key, cb) → {Promise}

Caches the results of a callback function in cache under the current namespace and returns the key's value.
Parameters:
Name Type Description
key string the app key to get from the current namespace.
cb function the callback function to get fresh value.
Source:
Returns:
the cached value.
Type
Promise

(static) cacheListAll(cache, namespace, pattern, includeErrors) → {Array|Object}

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.
Parameters:
Name Type Description
cache string the cache to list all keys from.
namespace string the namespace to list all keys from.
pattern string the key pattern to list all keys from.
includeErrors boolean whether to include error information in the response.
Source:
Returns:
returns an array of keys, or an object with keys and errors if includeErrors=true.
Type
Array | Object
Example
const result = await mcode.cacheListAll();
   const result = await mcode.cacheListAll({cache: 'node', namespace: '*', pattern: '*'});
   const {keys, errors} = await mcode.cacheListAll({includeErrors: true});

(static) cacheMakeKey(keySource) → {string}

Converts a 'key source' into a cache Key by replacing slashes with colons and removing spaces.
Parameters:
Name Type Description
keySource string the path to the key to be converted.
Source:
Returns:
the cache Key.
Type
string
Example
const keyPath = 'components/app/tool/tool.template.htmx';
    returns 'GM-GPS-eMITS-UI:components:app:tool:tool.template.htmx';

(static) cacheOff(cacheName) → {boolean}

Turns OFF caching for a specific namespace.
Parameters:
Name Type Description
cacheName string the name of the cache namespace to disable.
Source:
Returns:
true if the namespace was found and disabled, false otherwise.
Type
boolean

(static) cacheOn(cacheName) → {boolean}

Turns ON caching for a specific namespace.
Parameters:
Name Type Description
cacheName string the name of the cache namespace to enable.
Source:
Returns:
true if the namespace was found and enabled, false otherwise.
Type
boolean

(static) cacheSet(key, value) → {string}

Sets a key value in the cache.
Parameters:
Name Type Description
key string the app key to be set into current namespace.
value string the value to be set in the cache.
Source:
Returns:
the value set in the cache.
Type
string

(static) closeNamespace() → {Promise.<void>}

Closes all namespace-owned cache resources.
Source:
Returns:
resolves after all namespace resources close.
Type
Promise.<void>
Example
await mcode.closeNamespace();

(static) fileDrop(filePath) → {number}

Drops a file from the cache based on the 'filePath'.
Parameters:
Name Type Description
filePath string a standard file system reference to the file to be read.
Source:
Returns:
the number of keys deleted from the cache.
Type
number
Example
const filePath = './data.json';
    const result = await mcode.fileDrop(path.join(__dirname, filePath));

(static) fileGetRoot() → {string}

Gets the root directory for cache Keys based on the server's execution path.
Source:
Returns:
the root directory for the server.
Type
string
Example
const rootDir = mcode.fileGetRoot();

(static) fileMakeKey(filePath) → {string}

Generates a unique key for the file in the cache based on the 'filePath'.
Parameters:
Name Type Description
filePath string a standard file system reference to the file to be read.
Source:
Returns:
the key for the file in the cache.
Type
string

(static) fileRead(filePath, fileEncoding) → {string}

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).
Parameters:
Name Type Description
filePath string a standard file system reference to the file to be read,
fileEncoding string 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.
Source:
Returns:
the contents of the file read from 'path'.
Type
string
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.

(static) fileWrite(filePath, fileData, fileEncoding) → {Promise}

Writes 'fileData' to 'filePath' and caches it in the cache.
Parameters:
Name Type Description
filePath string a standard file system reference to the file to be read.
fileData string the data to be written to the file.
fileEncoding string the encoding of the file to be written (default is 'utf8').
Source:
Returns:
the file data written to disk.
Type
Promise

(static) getNamespace(name) → {object}

Returns an immutable handle for an existing cache namespace.
Parameters:
Name Type Description
name string the registered namespace name.
Source:
Throws:
when the namespace is not registered.
Type
Error
Returns:
the immutable namespace handle.
Type
object

(static) probeNamespace(config) → {object}

Performs a bounded Redis readiness and capability probe without registering a namespace.
Parameters:
Name Type Description
config object explicit Redis namespace configuration.
Source:
Returns:
probe status and server version.
Type
object

(static) refreshCacheStatistics() → {Promise}

Refreshes cache statistics for all Redis namespaces (async operation).
Source:
Returns:
Promise that resolves when statistics are updated.
Type
Promise
Example
await mcode.refreshCacheStatistics();