js-cache-tags (Simple and fast memory cache with tags support for Javascript/NodeJS projects)

A basic in memory cache module with tags support for Javascript/NodeJS projects. It's an extension of super useful and neat node cache library. It has basic set, get and del, delByTags methods and works a little bit like memcached. In addition to this, we can tag item while adding to cache and remove it based on tags as well. Keys can have a timeout (ttl) after which they expire and are deleted from the cache. All keys are stored in a single object so the practical limit is at around 1m keys.

Concept inspired by Drupal 8’s cache tags

Install

  npm install js-cache-tags --save

Or just require the js-cache-tags.min.js file to get the base class.

Examples

Initialize:

const JSCacheTags = require( "js-cache-tags" );
const myCache = new JSCacheTags();

const JSCacheTags = require( "js-cache-tags" );
const myCache = new JSCacheTags({ stdTTL: 100, checkperiod: 120 });

Options

• stdTTL: (default: 0) the standard ttl as number in seconds for every generated cache element. 0 = unlimited
• checkperiod: (default: 600) The period in seconds, as a number, used for the automatic delete check interval. 0 = no periodic check.
• errorOnMissing: (default: false) en/disable throwing or passing an error to the callback if attempting to .get a missing or expired value.
• useClones: (default: true) en/disable cloning of variables. If true you'll get a copy of the cached variable. If false you'll save and get just the reference. Note: true is recommended, because it'll behave like a server-based caching. You should set false if you want to save mutable objects or other complex types with mutability involved and wanted. Here's a simple code exmaple showing the different behavior
• deleteOnExpire: (default: true) whether variables will be deleted automatically when they expire. If true the variable will be deleted. If false the variable will remain. You are encouraged to handle the variable upon the event expired by yourself.

Store a key with tags (SET):

myCache.set(key, val, [tags], [ttl], [callback])

Sets a key value pair. You can attach tags (array). Also possible to define a ttl (in seconds). Returns true on success.

SET Example 1

obj = { name: "Viresh", age: 35 };
tags = ["tech geek", "foodie"]
myCache.set("myKey", obj, tags, 100, (err, success) => {
  if (!err && success) {
    console.log(success);
    // true
    // ... do something ...
  }
});

SET Example 2

obj = { name: "Viresh", age: 30 };
tags = [{"city": "Pune"}, {"country": "India"}]
success = myCache.set("myKey", obj, tags, 1000);

Retrieve a key (GET):

myCache.get(key, [callback], [errorOnMissing])

Gets a saved value from the cache. Returns a undefined if not found or expired. If the value was found then it returns an object with value.

try {
    myCache.get("myKey", (err, value) => {
        if (!err) {
            if (value == undefined) {
                // key not found
            } else {
                console.log(value);
                //{ name: "Viresh", age: 35 };
                // ... do something ...
            }
        }
    });
 } catch(err) {
    // ENOTFOUND: Key `not-existing-key` not found
 }

GET by tags (GetByTags):

myCache.getByTags(tags, [callback], [errorOnMissing])

Gets the items from cache by tags. Returns an empty array if not found. If the tag was found then it returns array of values for which tag was matched.

GET Example 1

myCache.getByTags(["tech geek"], (err, values) => {
    if (!err) {
        console.log(values);
        //[{ name: "Viresh", age: 35 }];
        // ... do something ...
    }
});

GET Example 2

myCache.getByTags([{"city": "Pune"}], (err, values) => {
    if (!err) {
        console.log(values);
        //[{ name: "Viresh", age: 35 }];
        // ... do something ...
    }
});

Delete by tags (DEL):

myCache.delByTags(tags, [callback] )

Delete item from cache by tags. Returns the number of deleted entries.

DELETE Example 1

myCache.delByTags(["tech geek"], (err, count) => {
    if (!err) {
        console.log(count); // 1
        // ... do something ...
    }
});

DELETE Example 2

myCache.delByTags([{"city": "Pune"}, {"country": "India"}], (err, count) => {
    if (!err) {
        console.log(count); // 1
        // ... do something ...
    }
});

DELETE Example 3

myCache.delByTags([123, 456], (err, count) => {
    if(!err){
        console.log(count); // 1
        // ... do something ...
    }
});

Special Thanks

js-cache-tags is extension to node-cache library (https://github.com/mpneuried/nodecache). Many thanks to Mathias Peter.

Happy Coding! Viresh Shah (http://www.vireshshah.com)