CachedGateway is a gateway for Mappersmith that wraps a transport gateway with a cache store to achieve transparent cache functionalities. It provides cache stores for browser and server.
npm install mappersmith-cached-gateway
Download the tag/latest version from the build folder.
Install the dependencies
npm install
Build
npm run build
npm run release # for minified version
For use in the server side.
var MappersmithCachedGateway = require('mappersmith-cached-gateway/node');
If you don't need any server features (like redis cache store) just require the module:
var MappersmithCachedGateway = require('mappersmith-cached-gateway');
Create and configure a CachedGateway is as simple as:
var manifest = {} // imagine that we have a manifest for Mappersmith
var MyCachedGateway = MappersmithCachedGateway.createCachedGateway()
var Client = new Mappersmith.forge(manifest, MyCachedGateway)
Without parameters MyCachedGateway
will be created with Mappersmith.VanillaGateway
and LocalStorageCacheStore
.
Use the first parameter of createCachedGateway
to configure your
transport gateway, for example, if we want to use Mappersmith.JQueryGateway
.
var manifest = {}
var JQueryGateway = Mappersmith.JQueryGateway;
var CGateway = MappersmithCachedGateway;
var MyCachedGateway = CGateway.createCachedGateway(JQueryGateway)
var Client = new Mappersmith.forge(manifest, MyCachedGateway)
Use the second parameter to configure your cache store. Check the list of available cache stores at the bottom of the readme.
var manifest = {}
var JQueryGateway = Mappersmith.JQueryGateway;
var CGateway = MappersmithCachedGateway;
var SSCacheStore = CGateway.SessionStorageCacheStore;
var MyCachedGateway = CGateway.createCachedGateway(JQueryGateway, SSCacheStore)
var Client = Mappersmith.forge(manifest, MyCachedGateway)
There are two options which can be configured for a cache store: namespace and ttl (Some cache stores may have specific options, check the list of available cache stores for a comprehensive list of options). The time to live (ttl) value can be defined globally and for each request using gateway options. It is possible to change the default ttl (the global value) through createCachedGateway
, just pass an object with the key ttl and the value in seconds.
var CGateway = MappersmithCachedGateway;
var JQueryGateway = Mappersmith.JQueryGateway;
var SSCacheStore = CGateway.SessionStorageCacheStore;
// With default transport gateway and cache store
CGateway.createCachedGateway({ttl: 10 * 60})
// With a custom transport gateway but with the default cache store
CGateway.createCachedGateway(JQueryGateway, {ttl: 10 * 60})
// With everything custom
CGateway.createCachedGateway(JQueryGateway, SSCacheStore, {ttl: 10 * 60})
The namespace goes to the same object:
var CGateway = MappersmithCachedGateway;
CGateway.createCachedGateway({ttl: 10 * 60, namespace: 'cache'})
Just use Mappersmith URL matching and include the option cache into the gateway option, example:
var manifest = {
host: 'http://my.api.com',
rules: [
{ // This will only be applied when the URL matches the regexp
match: /\/v1\/books/,
values: {gateway: {cache: {ttl: 15 * 60}}}
},
{
match: /\/v1\/photos/,
values: {gateway: {cache: {ttl: 2 * 60}}}
}
],
resources: {
Book: {
all: {path: '/v1/books.json'},
byId: {path: '/v1/books/{id}.json'}
},
Photo: {
byCategory: {path: '/v1/photos/{category}/all.json'}
}
}
}
There are two ways to do it:
- URL matching
var manifest = {
host: 'http://my.api.com',
rules: [
{ // This will only be applied when the URL matches the regexp
match: /\/v1\/books/,
values: {gateway: {cache: {disableCache: true}}}
}
],
resources: {
Book: {
all: {path: '/v1/books.json'},
byId: {path: '/v1/books/{id}.json'}
},
Photo: {
byCategory: {path: '/v1/photos/{category}/all.json'}
}
}
}
- Method call
Client.Book.byId({id: 3}, {cache: {disableCache: true}})
Client.Book.all({}, {cache: {disableCache: true}})
// or
Client.Book.byId(
{id: 3},
function(data, stats) {/* success callback */},
{cache: {disableCache: true}}
)
In the success callback Mappersmith will give to you a stats object as your second argument. With a cached gateway you will have the key cacheHit
with the value true if it was read from a cache store. Example:
...
Client.Book.byId({id: 3}, function(data, stats) {
// success callback
console.log('cache ' + (stats.cacheHit ? 'HIT' : 'MISS'))
})
...
CacheStore allows you to customize the cache layer. You can use the bundled implementations or write your own version.
LocalStorageCacheStore
Browser only. Require with MappersmithCachedGateway.LocalStorageCacheStore
.
SessionStorageCacheStore
Browser only. Require with MappersmithCachedGateway.SessionStorageCacheStore
.
NodeRedisCacheStore
Server only. Require with MappersmithCachedGateway.node.NodeRedisCacheStore
.
Extra options:
- client (e.g:
client: [6379, '127.0.0.1', options]
) - take a look at redis package for a complete list of options - logger (default: console) - use
logger: false
to disable the logger - password - it will issue an AUTH command if defined
- onError - callback to handle redis errors, the first argument is the error message
Example:
var cacheStore = new NodeRedisCacheStore({
redis: {
client: [6379, '127.0.0.1', {max_attempts: 10}],
password: 'foobar',
logger: false,
onError: function(err) {
console.error(err);
}
}
});
Take a look at node-redis-cache-store.js to further details.
MappersmithCachedGateway.createCacheStore({
init: function() {
// constructor, you have:
// - this.options
// - this.namespace
// - this.ttl
// - this.disableCache
},
read: function(name, callback) {
},
write: function(name, data, opts, doneCallback) {
},
delete: function(name, doneCallback) {
},
cleanup: function(doneCallback) {
},
clear: function(doneCallback) {
}
})
Take a look at cache-store.js to further docs.
Client
npm run test-browser
or SINGLE_RUN=true npm run test-browser
Server
npm run test-node
npm test
- Compile:
npm run build
- Release (minified version):
npm run release
See LICENSE for more details.