cashbox

cashbox

javascript cache library with configurable storage

---

npm install cashbox

Cashbox provides a common caching api on top of pluggable backend stores. memory and redis are currently the two supported stores, with memory being the default. Cashbox fully supports custom stores as long as they implement the correct api (see the memory store for an example of what to implement).

Using cashbox is pretty simple:

var Cashbox = require('cashbox');

// creates an in-memory cache by defaut
var cache = new Cashbox();

cache.set('myKey', 'myValue', function(err, wasSet) {

  cache.get('myKey', function(err, value) {
    console.log(value); //myValue
  });
  
});

// you can also set a ttl in seconds or a time string
cache.set('myKey', 'myValue', 10, function(err, wasSet) {

});

cache.set('myKey', 'myValue', '1 hour', function(err, wasSet) {

});

Cashbox API

---

Cashbox(config) constructor

The Cashbox constructor accepts an optional config object

• type can be set to specify cache store type. memory is the default, redis is also supported
• store can be set to either an instance, or a constructor for a backend cache store. The constructor will be passed the config object should it need any special configuration.

// a custom store instance, should implement the same api as the memory/redis store
var myCustomStore = new MyCustomStore();

// you can pass in the instance
var cache = new Cashbox({ store: myCustomStore });

// or the constructor - it will receive this same config object when instantiated
cache = new Cashbox({ store: MyCustomStore, foo: 'bar' });

• host can be set for redis store. Defaults to localhost
• port can be set for redis store. Defaults to 6379
• options can be set for redis store. These are connection options passed into the redis.createClient(host, port, options) call.

.get(key, load, ttl, callback)

• key is a string value used as the cache key
• load - Optionally pass a load function that will be called upon a cache miss.

// provide a function to load a missing value
function load(key, cb) {
  //load value from db or w/e
  doSomethingAsync(key, function(err, value) {
    if(err) return cb(err);
    
    // cb() expects error first, then value.  Optionally an array of tags can be passed in third 
    cb(null, value);
  });
}

cache.get(key, load, function(err, v) {
	// load() will have been called upon a cache miss
	console.log(v); // value returned from load()
});

• ttl is also optional, and may be specified w/ or w/o a load function. Supported formats for ttl are either a value in seconds, or a time string parseable by timestr (i.e. "1 hour")
• callback is called upon completion of fetching the value from the cache store. It is passed an error first, and the value. undefined is returned on cache misses