@truesparrow/unicache

UniCache is an open-source NPM package that provides unified / singleton interface and behavior for Memcached, Redis and In-memory caching. Easily interact or switch between them in minutes!

Why UniCache?

UniCache abstracts the unnecessary deviations between the base NPM packages of Memcached and Redis, in turn helping you learn about and interact with 3 different caching engines (Memcached, Redis and In-memory) all at once.
Singleton interface of UniCache is not only compatible with Memcached and Redis but also for In-Memory cache.
If your backend is interacting with multiple caching engines, UniCache helps developers to reduce translation layer for input and output - thus reducing development time and effort. Even exceptions are given out consistently.
When using multiple caching engines simultaneously or want to switch between them, consistent output from UniCache will help in faster development.
Be rest assured that your code will not need any further changes in order to use the upcoming base NPM package versions. UniCache will take care of it.
UniCache is thoroughly tested and is fully compatible with AWS ElastiCache for Redis and AWS ElastiCache for Memcached.

Prerequisites

Node.js (>= version 6)
NPM

Follow the installation guides to get the caching engines of your choice, up and running:

Install NPM

npm install @truesparrow/unicache --save

Initialize

While using the package, create a singleton object of UniCache for each caching engines and then use it across the application. Example snippet for the UniCache singleton object initialization is given below.

// Include the following snippet in a separate file, which can be required all accross the code to get unicache instance.
// If using different caching engines simultaneously in a single codebase, have different files for each.
const UniCache = require('@truesparrow/unicache');

const configStrategy = {
  engine: "none/redis/memcached",
  // Other keys depend on the engine, refer to the next section on Config Strategy, for the same.
};

module.exports = UniCache.getInstance(configStrategy);

The singleton object can be used as given below.

const cacheProvider = require('path-to-your-uni-cache-singleton-provider');
const cacheImplementer = cacheProvider.cacheInstance;

cacheImplementer.set('testKey', 'testValue', 5000).then(console.log);
cacheImplementer.get('testKey').then(console.log);

Note: To print detailed logs, add UNICACHE_DEBUG_ENABLED = '1' in the ENV variables.

Config Strategy

configStrategy is a mandatory parameter which specifies the configuration to be used for the caching engine. Using the engine property, you can select which caching engine to use.

An example of the configStrategy is:

const configStrategy = {
    engine: "none/redis/memcached",
  // other keys depend on the engine.
};

Redis Config Strategy

Following is how the config strategy looks for redis caching engine.

const configStrategy = {
  engine: "redis",
  host: "localhost",
  port: "6380",
  password: "dsdsdsd",
  enableTsl: "0",
  defaultTtl: 36000,
  consistentBehavior: "1"
}

engine: Pass value redis for using UniCahce with Redis.
host: Host of the Redis server.
port: Port of the Redis server.
password: Password for auth with Redis server.
enableTsl: Pass '1' for enabling TSL. Otherwise '0'
defaultTtl: Default time to live (TTL) for cache in seconds.
consistentBehavior: Pass '1' to use the consistent behaviour accross various caching engines option. Otherwise '0'.

Memcache Config Strategy

Following is how the config strategy looks for Memcache caching engine.

const configStrategy = {
  engine: "memcached",
  servers: ["127.0.0.1:11211"],
  defaultTtl: 36000,
  consistentBehavior: "1"
}

engine: Pass value memcached for using UniCahce with Memcache.
servers: Servers is an array of memcached servers' hosts.
defaultTtl: Default time to live (TTL) for cache in seconds.
consistentBehavior: Pass '1' to use the consistent behaviour accross various caching engines option. Otherwise '0'.

In-Memory Config Strategy

Following is how the config strategy looks for In-memory caching engine.

const configStrategy = {
  engine: "none",
  namespace: "A",
  defaultTtl: "36000",
  consistentBehavior: "1"
}

engine: Pass value none for using UniCahce with In-memory cache.
namespace: In-memory cache namespace. You can segregate cache keys in the same machine with different namespaces.
defaultTtl: Default time to live (TTL) for cache in seconds.
consistentBehavior: Pass '1' to use the consistent behaviour accross various caching engines option. Otherwise '0'.

`cacheImplementer` methods

Irrespective of the caching engine, the methods exposed in cacheImplementer have the consistent signature, i.e. singleton interface implementation.

Store and retrieve data in cache using `set` and `get`:

const resolvePromise = function(cacheResponse){
                           if (cacheResponse.isSuccess()) {
                             console.log(cacheResponse.data.response);
                           } else {
                             console.log(cacheResponse);
                           }
                         };

cacheImplementer.set('testKey', 'testValue', 5000).then(resolvePromise);

cacheImplementer.get('testKey').then(resolvePromise);

Manage objects in cache using `setObject` and `getObject`:

cacheImplementer.setObject('testObjKey', {dataK1: 'a', dataK2: 'b'}).then(resolvePromise);
cacheImplementer.getObject('testObjKey').then(resolvePromise);

Retrieve multiple cache data using `multiGet`:

NOTE: Redis returns null from multiGet for objects, even if a value is set in the cache. The other caching implementers match this behaviour.

cacheImplementer.set('testKeyOne', 'One').then(console.log);
cacheImplementer.set('testKeyTwo', 'Two').then(console.log);
cacheImplementer.multiGet(['testKeyOne', 'testKeyTwo']).then(resolvePromise);

Delete cache using `del`:

cacheImplementer.set('testKey', 'testValue').then(console.log);
cacheImplementer.del('testKey').then(resolvePromise);

Manage counters in cache using `increment` and `decrement`:

cacheImplementer.set('testCounterKey', 1).then(console.log);
cacheImplementer.increment('testCounterKey', 10).then(resolvePromise);
cacheImplementer.decrement('testCounterKey', 5).then(resolvePromise);

Change the cache expiry time using `touch`:

cacheImplementer.set('testKey', "testData").then(console.log);
cacheImplementer.touch('testKey', 10).then(resolvePromise);

Test Cases

Test cases cover all the 3 caching engines. Also a coverage report is generated at the end. Running test cases is a 2 step process.

Step 1: Start Cache Engines

Following processes are needed for running test cases.

Start Redis on 2 ports - 6380 and 6381 as needed by the test cases.

redis-server --port 6380
redis-server --port 6381

Start Memcached on 4 ports - 11212,11213,11214 and 11215 as needed by the test cases.

memcached -p 11212 -d
memcached -p 11213 -d
memcached -p 11214 -d
memcached -p 11215 -d

Step 2: Run tests

For running tests for all the 3 caching engines, use the following command.

npm run test

Contribution

We welcome more helping hands to make UniCache better. Feel free to report issues, raise PRs for fixes & enhancements.

Built with ❤️ by True Sparrow