@mediaxpost/object-key-cache v1.4.2
object-key-cache
object-key-cache
is a promise-based, object-key, cache extension for the Redis and memory-cache modules.
Object Key Cache provides the ability to use JavaScript Objects as keys values when committing to cache.
During connection to Redis, it defaults to fail-back to the memory cache when when connecting to Redis fails.
Object Keys that are passed into the associated o--- functions (e.g. oget, oset, etc.) are JSON stringified and then SHA256 hashed in an attempt to preserve the uniqueness of the key. Note:* No additional mitigation of potential collision of key spaces with SHA256 is being performed. With one billion messages there is approximately a 1 in 4.3 x 1060 chance with SHA256 that two separate strings will generate an identical hash. The probability is negligible for most use cases; however, if very, very large numbers of keys are likely to be stored then consideration should be given to name-spacing or segregating data by how it will be used within the cache to avoid any potential for collisions.
Installation
npm install @mediaxpost/object-key-cache
Usage
const ObjectKeyCache = require('@mediaxpost/object-key-cache');
const objKeyCache = new ObjectKeyCache();
const testObj = { name: 'test key' };
objKeyCache.connect()
.then(() => {
return objKeyCache.oset(testObj, 100);
})
.then(() => {
return objKeyCache.oget(testObj);
})
.then((result) => {
console.log(result); // 100
return objKeyCache.close();
})
.catch((err) => {
// Do something meaningful
});
API Reference
With noted exceptions, all functions are Promise-based (meaning they return a Promise which should be handled)
constructor(options , redisCredentials)
Create a new ObjectKeyCache client with the passed options, credentials, and logger. The options
support only value failover
which defaults to true
and causes any connection attempts to Redis to fail-back to the memory Cache. Any other options provided are passed along to the Redis or MemoryCache createClient
function. If redisCredentials
are passed, then ObjectKeyCache will attempt to connect to Redis. If they are omitted or set null
then Memory Cache is used. The log
is a Logging object outlined below.
.attachToClient(redisClient)
Attaches an unconnected ObjectKeyCache to an already existing and connected RedisClient.
.detachFromClient()
Detaches ObjectKeyCache from a connected RedisClient.
.connect() ⟾ Promise
Connects to the cache and set the connected
flag to true
. The Promise resolves to the cache connection.
.close() ⟾ Promise
Disconnects from the cache and set the connected
flag to false
. The promise resolves to the cache connection.
.calcObjKey(obj) ⟾ string
Returns the SHA256 Hash of the message resulting from the JSON stringified obj
.
.clear() ⟾ Promise
Clears the cache for the currently connected database within the cache. This is equivalent to running FLUSHDB
. The promise resolves to the Redis/MemoryCache messages (usually 'OK').
.oget(obj) ⟾ Promise
Retrieves a value stored with the object key obj
. The promise resolves to the result or null
if it doesn't exist.
.oset(obj, value) ⟾ Promise
Sets a value with an object key obj
. The promise resolves to the Redis/MemoryCache messages (usually 'OK').
.odel(obj) ⟾ Promise
Deletes the object key obj
. The promise resolves to the Redis/MemoryCache messages (usually 'OK').
.ohget(hash, obj) ⟾ Promise
Retrieves the Hash object key obj
field that is scoped to the hash
. The promise resolves to the result or null
if it doesn't exist.
.ohset(hash, obj, value) ⟾ Promise
Sets the Hash object key obj
field that is scoped to the hash
to value value
. The promise resolves to the Redis/MemoryCache messages (usually 'OK').
.ohdel(hash, obj) ⟾ Promise
Deletes the object key obj
field scoped to the hash
. The promise resolves to the Redis/MemoryCache messages (usually 'OK').
.get(key) ⟾ Promise
Retrieves the key
from the cache. The promise resolves to the result or null
if it does not exist.
.set(key, value) ⟾ Promise
Sets the key
to the value
. The promise resolves to the Redis/MemoryCache messages (usually 'OK').
.del(key) ⟾ Promise
Deletes the key
. The promise resolves to the Redis/MemoryCache messages (usually 'OK').
.hget(hash, field) ⟾ Promise
Retrieves the field
that is scoped to the hash
. The promise resolves to the result or null
if it does not exist.
.hset(hash, field, value) ⟾ Promise
Sets the field
that is scoped to the hash
to the value
. The promise resolves to the Redis/MemoryCache messages (usually 'OK').
.hdel(hash, field) ⟾ Promise
Deletes the field
scoped to the hash
. The promise resolves to the Redis/MemoryCache messages (usually 'OK').
Appendix
Redis Credentials
The Redis credentials define how to connect to Redis and are an object as follows:
{
port: 6379,
host: 'localhost'
}
Logging Object
The Logging object is an instance of any logging library, such as Winston or Bunyan, which support the .error(...)
, .info(...)
, .debug(...)
, and .log(...)
methods. If this is not provided, then any debug or error messages are sent to /dev/null
.