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 10⁶⁰ 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] [, 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.