A promise-based cache store that preserves stored data types and is easily expandable with custom cache stores. Redis is supported out of the box.

Inspired by Laravel's Cache

npm install promise-cache

This code is assumed existing in all of the upcoming examples.

Cache = require('promise-cache').create()

Cache.put('key', 'value', 20); // will be stored for 20 seconds.

Cache.forever('other', 'thing'); // will be stored indefinitely

Cache.get('key').then(function(result){
    console.log(result); // value will be whatever we have stored.
});

Since Cache works in promises then you may assign the operation to a variable and attach handlers to it:

found = Cache.get('key');

found.then(function(value){
    // do things with the value.
});

found.then(function(value){
    // do something else with the value.
});

found.fail(function(why){
    // something went wrong while fetching, see why.
});

Sometimes you may wish to perform a certain operation and store its results if the data you're looking for was not found in the cache. This can be achieved using remember or rememberForever methods.

Cache.remember('some-key', 22, function(store){
    data = 'do something to get the data';

    store(data);
});

Http = require('promise-http').client;

cached = Cache.remember('onetwo', 60, function(store){
    request = Http.get('http://echo.jsontest.com/key/value/one/two')
    request.then(function(response){
        // store the JSON representation of the response.
        store(JSON.prase(response));
    });
});

// data will be remembered for 60 seconds and the request will be issued
// again when the time has elapsed.
cached.then(function(data){
    console.log('do things with data');
});

The above example with rememberForever would store the data forever:

Http = require('promise-http').client;

forever = Cache.rememberForever('threefour', function(store){
    request = Http.get('http://echo.jsontest.com/key/value/three/four')
    request.then(function(response){
        // store the JSON representation of the response.
        store(JSON.parse(response));
    });
});

// data will forever be stored (until flushed or removed by someone else)
forever.then(function(data){
    console.log('do things with the data, again.');
});

As you can see, regardless of the type of data we are storing, promise-cache will make sure to return just what you stored preserving the data types for you - all data types are supported.

You may configure the redis store or specify another store you have built yourself. This package uses redis-pool to manage Redis connections. The object passed to the redis property will be used as the settings for the RedisPool constructor.

The values listed below are the defaults.

Cache = require('promise-cache').create({
    prefix: 'pcache',
    ttl: 60,
    redis: {
        host: '127.0.0.1',
        port: 6379,
        pool:{
            max: 1,
            min: 1
        }
    }
});

You may also have different instances connected to different stores.

LocalCache = require('promise-cache').create();

CentralCache = require('promise-cache').create({
    redis: {host: '192.168.53.69'}
});

Custom store: check the Custom Store section

Cache = require('promise-cache').create({
    store: './stores/RedisStore' // set the /path/to/your/store
});

Get the cache key.

• mixed key

• string

Store an item in the cache for a given number of seconds.

• mixed key
• mixed value
• int ttl

• q.promise Deferred Promise.

Store an item in the cache indefinitely.

• mixed key
• mixed value

• q.promise

Get an item from cache if it exists, otherwise call closure and store the results.

• mixed key
• function closure

Just like remember(), get an item from the cache or store the resulting value from the promise.

• mixed key
• function closure

Determine if an item exists in the cache.

• mixed key

• q.promise

Increment the value of an item in the cache.

• mixed key
• int count (Default 1)

• q.promise

Decrement the value of an item in the cache.

• mixed key
• int count (Default 1)

• q.promise

Get the remaining TTL (Time To Live) of an item in the cache.

• mixed key

Retrieve an item from the cache by key.

• mixed key

• q.promise

Remove an item from the cache by key.

• mixed key

• q.promise

Remove all items from the cacheKey

• q.promise

To implement your own store, the following methods needs to be implemented.

• cb is the callback function that needs to be called with (error, result)
  • error should be null in the case of no errors. Otherwise the cache promise will be rejected.
  • result is the result of the operation.

Set an item by key.

• string key
• string value
• function cb

Set an item by key for a certain number of minutes.

• string key
• string value
• int ttl
• function cb

Determine whether an item exists in the store.

• string key
• function cb

Get the TTL of an item.

• string key
• function cb

Get an item from the store.

• string key
• function cb

Delete an item from the store.

• string key
• function cb

Flush the store.

• function cb

Increment the integer value of a key by @count. Default is 1.

• string key
• int count
• function cb

Decrement the integer value of a key by @count. Default is 1.

• string key
• int count
• funciton cb

The tests for this package are divided into two. One in spec/ and the other is in test/ where they represent unit testing and functional testing respectively.

• First: npm install
• Running specs: npm run-script spec
• Running tests:
  • Make sure to have a Redis instance running if you're using the default store. i.e. docker run -d -p 6379:6379 redis
  • if configuration is needed set it up in test/config.coffee
  • npm run-script test