Constructor
new cache() → {cache}
Creates or returns the singleton cache instance.
Returns:
the singleton cache instance.
- Type
- cache
Members
cacheErrors
Properties:
| Name | Type | Description |
|---|---|---|
cacheErrors |
object | the frozen stable package error codes for operational branching. |
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(). |
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. |
cacheReady
Properties:
| Name | Type | Description |
|---|---|---|
cacheReady |
boolean | whether the cache instance and configured Redis namespaces are ready. |
cacheTTL
Properties:
| Name | Type | Description |
|---|---|---|
cacheTTL |
number | the cache Time-To-Live property, in seconds. |
redisMinimumVersion
Properties:
| Name | Type | Description |
|---|---|---|
redisMinimumVersion |
string | the minimum supported Redis server version. |
redisPassword
Properties:
| Name | Type | Description |
|---|---|---|
redisPassword |
string | the Password to the Redis Server. |
redisPort
Properties:
| Name | Type | Description |
|---|---|---|
redisPort |
string | the PORT to the Redis Server. |
redisStatus
Properties:
| Name | Type | Description |
|---|---|---|
redisStatus |
object | the frozen stable Redis namespace status constants. |
redisURL
Properties:
| Name | Type | Description |
|---|---|---|
redisURL |
string | the URL to the Redis Server. |
redisUser
Properties:
| Name | Type | Description |
|---|---|---|
redisUser |
string | the User to the Redis Server. |
(static) cache#cacheNamespace
Sets the default namespace for subsequent singleton cache operations.
Properties:
| Name | Type | Description |
|---|---|---|
cacheNamespace |
(static) cache#cacheTTL
Sets the default cache Time-To-Live in seconds.
Properties:
| Name | Type | Description |
|---|---|---|
cacheTTL |
(static) cache#redisPassword
Sets the legacy Redis password.
Properties:
| Name | Type | Description |
|---|---|---|
redisPassword |
(static) cache#redisPort
Sets the legacy Redis server port.
Properties:
| Name | Type | Description |
|---|---|---|
redisPort |
(static) cache#redisURL
Sets the legacy Redis server URL.
Properties:
| Name | Type | Description |
|---|---|---|
redisURL |
(static) cache#redisUser
Sets the legacy Redis username.
Properties:
| Name | Type | Description |
|---|---|---|
redisUser |
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. |
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. |
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. |
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. |
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. |
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. |
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. |
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. |
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. |
Returns:
the cached value.
- Type
- Promise
(static) _cacheInit() → {status}
Initializes the internals of mcode-cache, including the instantiation of the cache client.
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. |
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. |
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. |
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. |
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. |
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. |
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. |
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. |
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. |
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. |
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. |
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. |
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. |
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. |
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. |
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. |
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. |
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. |
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. |
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. |
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. |
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. |
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. |
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'). |
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. |
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. |
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. |
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. |
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. |
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. |
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. |
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. |
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. |
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. |
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. |
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. |
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. |
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. |
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. |
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. |
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. |
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. |
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. |
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. |
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. |
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. |
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. |
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. |
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. |
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. |
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. |
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. |
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. |
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. |
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. |
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. |
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. |
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. |
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. |
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. |
Returns:
- Type
- void
(static) _updateNamespaceStatistics() → {void}
Updates cache statistics for all namespaces.
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. |
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. |
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. |
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. |
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. |
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. |
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. |
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. |
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. |
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. |
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. |
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. |
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. |
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. |
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. |
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. |
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. |
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. |
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. |
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. |
Returns:
the value set in the cache.
- Type
- string
(static) closeNamespace() → {Promise.<void>}
Closes all namespace-owned cache resources.
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. |
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.
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. |
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. |
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'). |
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. |
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. |
Returns:
probe status and server version.
- Type
- object
(static) refreshCacheStatistics() → {Promise}
Refreshes cache statistics for all Redis namespaces (async operation).
Returns:
Promise that resolves when statistics are updated.
- Type
- Promise
Example
await mcode.refreshCacheStatistics();