README.md

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 10⁷⁷ 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.