@outofsync/object-key-cache
v2.0.3
Published
A Promise-based, object-key, cache extension for Redis and MemoryCache.
Downloads
45
Readme
object-key-cache
object-key-cache
is a promise-based, object-key, cache extension for the Redis and memory-cache modules.
Object Key Cache converts JavaScript Objects (Maps) into the key value used to look up data from cache. This is done by serializing the object into JSON (e.g. JSON.stringify
) and then performing a SHA256 has on the resulting JSON string. This process helps preserve the uniqueness of the key for performing lookups. Once the key has been generated, the key-value pair is passed into the associated Oxxx functions (e.g. oget, oset, etc.)
Note: SHA512 has a very low likelihood of key space collisions, but it is not impossible. With one billion messages there is approximately a 1 in 1.4 x 1077 chance that two distinct strings will generate an identical SHA512 hash. This probability is negligible for most use cases; however, if a very large numbers of keys are expected to be stored then consideration should be given to segregating data by a namespace based upon how it will be used within the cache to decrease any potential for collisions.
This module has been updated to support NodeJS 18 or higher.
Installation
npm install @outofsync/object-key-cache
Usage
const ObjectKeyCache = require('@outofsync/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] [, log])
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
.
License
Copyright (c) 2018-2019 Jay Reardon Copyright (c) 2019-2021 Out of Sync Studios LLC -- Licensed under the MIT license.