vogels-cache

Vogels-cache adds a cache layer (backed by Redis) to your Vogels or Dynogels models.

Installation

npm install vogels-cache --save

Usage

First you need to configure Vogels-cache with a redis client:

var redis = require("redis").createClient();
var vogelsCache = require('vogels-cache');
vogelsCache.setRedisClient(redis);

Then you can use Vogels-cache to create cacheable version of a Vogels or Dynogels model (the original Model will not be altered):

var vogels = require('vogels');
//do vogels setup
var Account = vogels.define('Account', {
  hashKey : 'email',
  schema : {
    email   : Joi.string().email(),
    name    : Joi.string(),
    age     : Joi.number(),
  }
});
 
var CacheableAccount = vogelsCache.prepare(Account);
//now you can use CacheableAccount as a Vogels Model:
var account = CacheableAccount({
    email: '[e-mail]',
    name: 'foo',
    age: 30
});
//save will automatically save the model to redis
account.save();

Cache options

When preparing a Model will can pass some options to vogels-cache:

var CacheableAccount = vogelsCache.prepare(Account,{
    CACHE_RESULT: true, //if all data returned from dynamodb will be cached (default: true)
    CACHE_SKIP: false, //if will skip cache and get data directly from DynamoDB (default:false)
    CACHE_EXPIRE: 3600, //duration (in seconds) that the item will be in cache (default:undefined, forever)
    redis: undefined //redis client can be setted by model
});

You can also pass those 3 first options per request, as Dynamo options:

CacheableAccount.get('[e-mail]',{CACHE_SKIP:true,CACHE_RESULT:false},function(err,acc){
    //got the account directly from DynamoDB and didn't added it to redis
});

OBS: cache options are removed before sending the request to DynamoDB

Model Methods

This is the behavior of each method will have when using its cacheable version (the methods have the same signature as the uncached Vogels Model):

.get(hashKey, rangeKey, options, callback)

Will try to get item from cache and fallback to DynamoDB. After retrieving the item from DynamoDB, cache it. Accept options CACHE_SKIP:true and CACHE_RESULT:false to change this behavior.

.create(attrs,options,callback)

Create the item in DynamoDB and then cache it. Accept CACHE_RESULT:false option to prevent caching.

.update(item, options, callback)

The returned item will NOT be cached and the item will be removed from cache (if it exists). You can change this behavior by sending CACHE_RESULT:true as an option.

.destroy(hashKey, rangeKey, options, callback)

Remove item from cache after sucessfull deletion from DynamoDB.

.uncache(hashKey, rangeKey, callback)

Remove item from cache only.

.query(), .scan(), .paralellScan()

By default will NOT cache items returned in response. If this is not the desired behavior, use the function .cacheResults(shouldCache,expire):

CacheableAccount.query('foo').cacheResults(true).exec(function(err,items){
    //items will not be cached
});

getItems(keys, options, callback)

First try to get all items from cache and then get missing ones from Dynamo. Tries to keep the returned items in order based on the requested keys order. Add option CACHE_SKIP:true to fetch directly from Dynamo. Also accept CACHE_RESULT:false option to prevent caching results.

Item Methods

Item methods also have other behaviors in they cacheable version (they also share the same method signature of the original Vogels Item):

.save(callback)

Cache the model after a sucessfull save. This method dont't allow options (just like Vogels).

.update(options,callback)

The updated version of the model is not cached and if there is a cached version of this item, it will be removed from cache. You can change this behavior by sending CACHE_RESULT:true as an option.

.destroy(options,callback)

Delete the model from cache after destroying.

.uncache(callback)

Removes the model from cache only.

How to know if an item was cached or came from cache

Every item object cached by Vogels-cache will have the property cached setted with the time it whas cached. Every item that was fetched from cache will have the property fromCache setted to the time it was fetched from cache. Note that those two properties are setted to the Item object.

CacheableAccount.get('foo',{CACHE_SKIP:true},function(err,item){
    item.cached; //will have the cache time
    item.fromCache; //will be undefined, because we skipped cache
    item.get('email'); //item data
});

Caveats

• GET MODIFICATORS: Be careful when caching .get() results with AttributesToGet or ProjectionExpression. Use options CACHE_RESULT and CACHE_SKIP to achieve the desired results
• CACHING UPDATES: If you want to cache with an .update() use the option CACHE_RESULT:true, but be carefull with the parameter ReturnValues (NONE | ALL_OLD | UPDATED_OLD | ALL_NEW | UPDATED_NEW). That is why the default behavior is to NOT cache updates requests.

Changelog

• 1.8.1
  • Updated dependencies
• 1.8.0
  • Added option CACHE_RESULT to .update() to force caching updates per request
• 1.7.1
  • Minimum node version supported is now 4.0.0
• 1.7
  • Added support to Dynogels
• 1.6
  • Don't cache updates anymore. And the item will be removed from cache after a successful update.

License

(The MIT License)

Copyright (c) 2017 Adriano Cola

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.