A tiered caching solution for JavaScript.
Upgrading from an older version? Please see the Breaking Change History section.
Do you use superagent? Check out superagent-cache to get superagent queries with cache-service built right in.
cache-service allows you to create redundant, cache-agnostic caching configurations. I've supplied a redis wrapper and node-cache wrapper as separate npm modules, but you can add any cache you want as long as you follow the same interface.
Require and instantiate cache-service as follows:
var cs = require('cache-service');
var cacheService = new cs();This gives you the default configuration. Now you can cache like normal with the benefit of a tiered solution:
function getData(key, cb){
cacheService.get(key, function (err, response){
if(!err){
cb(err, response);
}
else{
performQuery(key, function (err, response){
var value = response.body.user;
cacheService.set(key, value);
cb(err, value);
});
}
});
}npm install cache-service --savenpm testBy following the Basic Usage example above, cache-service will:
- use all the default values shown in the Cache Service Configuration Object section
- provide you with an instance of cacheModule
All caches will have a defaultExpiration of 900 seconds unless specified otherwise.
To use a custom configuraiton, take advantage of the the two optional params you can hand to cache-service's constructor as follows:
//Require the desired modules (make sure to add them to your package.json)
var nodeCacheModule = require('cache-service-node-cache');
var redisModule = require('cache-service-redis');
var cs = require('cache-service');
//Instantiate your cache modules
var nodeCache = new nodeCacheModule({defaultExpiration: 500});
var redisCache = new redisModule({redisEnv: 'REDISCLOUD_URL'});
//Setup your cache-service constructor params
var cacheServiceConfig = {verbose: true};
var cacheModules = [nodeCache, redisCache];
//Instantiate cache-service
var cacheService = new cs(cacheServiceConfig, cacheModules);This code block will result in a tiered cache-service instance that uses a primary in-memory cache and a fallback redis cache. For more information on what cache modules are available, see the Available Cache Modules section.
cache-service's constructor takes two parameters in the following order: cacheServiceConfig and cacheModules:
var cacheService = new cs(cacheServiceConfig, cacheModules);This is where you set cache-service-level config options. Here are all the available options:
A namespace to be applied to all keys generated for this instance of cache-service.
- type: string
- default: empty string
When false, cache-service will log only errors. When true, cache-service will log all activity (useful for testing and debugging).
- type: boolean
- default: false
Let's say you have an instance of cache-service with two caches inside of it: cacheA and cacheB. If cacheA has a shorter defaultExpiration than cacheB and cacheA does not have the key for which you're looking, cache-service will then look in cacheB. If cache-service finds the desired key in cacheB and writeToVolatileCaches is true, cache-service will then write that key to cacheA.
This is particularly useful if you want to have a short-term in-memory cache with the most used queries and a longer-term redis cache with all of the cached data.
- type: boolean
- default: true
This is where you give cache-service the pre-instantiated caches you want it to use. Here's an example cacheModules array:
//Instantiate some cache modules
var nodeCacheInstance = new nodeCacheModule({defaultExpiration: 500});
var redisCacheInstance = new redisCacheModule({redisEnv: 'REDISCLOUD_URL'});
//Place the new cache modules into the cacheModules array
var cacheModules = [
nodeCacheInstance
redisCacheInstance
]This cacheModules array will provide a primary node-cache instance with a fallback redis cache. The node-cache instance would have a 500-second defaultExpiration and the redis instance would have a 15-minute default expiraiton.
As you can see in the Cache Modules Array example above, each cache module constructor takes an object. This object is a cacheModuleConfig object. I've added a more explicit example below for clarity:
var cacheModuleConfig = {defaultExpiration: 500, readOnly: true};
var cacheModule = new nodeCacheModule(cacheModuleConfig);
var cacheModules = [cacheModule];Every cache module, regardless of the type of cache its wrapping, accepts a cacheModuleConfig in its constructor. While the properties accepted by a given cache module's cacheModuleConfig may vary, the properties listed below should always be available in all cache modules. If you need to know what unique cacheModuleConfig properties a specific cache module accepts, visit that cache module's documentation.
An arbitrary identifier you can assign so you know which cache is responsible for logs and errors.
- type: string
- default: the name of the cache type ('redis' or 'node-cache' etc.)
The expiration to include when executing cache set commands. Can be overridden via .set()'s optional expiraiton param.
- type: int
- default: 900
- measure: seconds
By default, if two subsequent caches have the same defaultExpiraiton, the second of the two caches will be checked in the event that the first cache does not have a key. If checkOnPreviousEmpty is false, cache-service will not check subsequent caches with the same defaultExpiration.
- type: boolean
- default: true
Whether a cache should not be written to. Useful if you're sharing a redis cache with another team and your contract with them is that you will not alter their data.
- type: boolean
- default: false
Retrieve a value by a given key. All available cache modules attempt to JSON.parse all values returned from .get() and JSON.stringify all values passed to .set().
- key: type: string
- callback: type: function
- err: type: object
- response: type: string or object
Retrieve the values belonging to a series of keys. If a key is not found, it will not be in response.
- keys: type: an array of strings
- callback: type: function
- err: type: object
- response: type: object, example: {key: 'value', key2: 'value2'...}
See the Using Background Refresh section for more about the
refreshandcallbackparams.
Set a value by a given key. All available cache modules attempt to JSON.stringify all values passed to .set() and JSON.parse all values returned from .get().
IMPORTANT: The
callbackparam takes precedence over therefreshparam. This means that, when only four arguments are passed and the last param is a function,cache-servicewill assume the last param iscallback. Similarly, if three params are passed and the third is a function,cache-servicewill assume the third param iscallbackrather thanrefresh. This is done to maintain backwards compatibility with versions released before thebackground refreshfeature was added.
- key: type: string
- callback: type: function
- expiration: type: int, measure: seconds
- refresh: type: function
- callback: type: function
Set multiple values to multiple keys
- obj: type: object, example: {'key': 'value', 'key2': 'value2', 'key3': {cacheValue: 'value3', expiration: 60}}
- callback: type: function
This function exposes a heirarchy of expiration values as follows:
- The
expirationproperty of a key that also contains acacheValueproperty will override all other expirations. (This means that, if you are caching an object, the string 'cacheValue' is a reserved property name within that object.) - If an object with both
cacheValueandexpirationas properties is not present, theexpirationprovided to the.mset()argument list will be used. - If neither of the above is provided, each cache's
defaultExpirationwill be applied.
Delete a key or an array of keys and their associated values.
- keys: type: string || array of strings
- callback: type: function
- err: type: object
- count: type: int
Flush all keys and values from an instance of cache-service.
- callback: type: function
IMPORTANT: While this property is available for viewing, modifying it at run time will almost certainly break cache-service.
This is the cacheModules array you passed as the second param to the constructor.
With a typical cache setup, you're left to find the perfect compromise between having a long expiration so that users don't have to suffer through the worst case load time, and a short expiration so data doesn't get stale. cache-service eliminates the need to worry about users suffering through the longest wait time by automatically refreshing keys for you.
By default, background refresh is off. It will turn itself on the first time you pass a refresh param to .set().
cache-service relies on the background refresh feature of the final cache you pass in the cacheModules array. When you call .set() and pass refresh and callback params, cache-service routes the provided refresh param to ONLY the final cache in the cacheModules array. This means that you almost certainly want cache-service's writeToVolatileCaches property set to true (it defaults to true) so that the refresh written to the final cache will propogate forward to earlier caches
If desired, configure the following properties in the final cache in the cacheModules array:
backgroundRefreshIntervalbackgroundRefreshMinTtlbackgroundRefreshIntervalCheck
Background refresh is exposed via the .set() command as follows:
cacheModule.set('key', 'value', 300, refresh, cb);If you want to pass refresh, you must also pass cb because if only four params are passed, cache-service-node-cache will assume the fourth param is cb.
- key: type: string: this is the key that is being refreshed
- cb: type: function: you must trigger this function to pass the data that should replace the current key's value
The refresh param MUST be a function that accepts key and a callback function that accepts err and response as follows:
var refresh = function(key, cb){
var response = goGetData();
cb(null, response);
}A redis wrapper for cache-service or standalone use. Available on NPM.
An in-memory cache wrapper for cache-service or standalone use. Available on NPM.
A super-light in-memory cache for cache-service or standalone use. (This module is bundled with cache-service and provided in the default configuration if you do not provide a cacheModules constructor param.) Available on NPM.
cache-service allows you to inject any cache type that matches the Cache Module Interface. Any such modules should be stored in a separate NPM package so that you can include exactly what you need in your app and nothing more. I've provided a redis wrapper as an NPM module, so let's use that one for the purposes of these examples. To install a cache module, locate the cache-service-compatible package you want to use (we'll use cache-service-redis), then install it as follows:
npm install cache-service-redis --saveNow that you've installed the cache modules you want, go ahead and require them in your project:
var redisCacheModule = require('cache-service-redis');To instantiate it, simply pass a Cache Module Configuration object:
var redisCacheInstance = new nodeCacheModule({
redisEnv: 'REDISCLOUD_URL',
defaultExpiration: 60,
cacheWhenEmpty: false
});Now let's pass our manually instantiated redisCacheInstance into our cache-service constructor:
var cacheService = new cs({}, [
redisCacheInstance
]);Any cache can be used with cache-service as long as it follows the cacheModule interface. Whether you'd like to wrap your own cache for your app or create a new NPM module so everyone can benefit from your work, your cache wrapper should follow the instructions below.
Your cache wrapper must define the following top-level properties. Detailed descriptions for each of these can be found in the Cache Module Configuration Object documentation.
Your cache wrapper must define any of the following top-level functions you plan to use. Detailed descriptions for each of these can be found in the API documentation. (If you're making an open-source package rather than just using your custom cache wrapper on your own, please include all functionality.)
Once your cache meets the requirements listed above, you can follow the Install, Require, Instantiate, and Inject instructions to use it directly.
If this explanation doesn't cut it for you, have a look at cache-service-cache-module, cache-service-node-cache, and cache-service-redis to see how I'm doing it.
If you decide to create an open-source cache module for use with cache-service, please start your module name with 'cache-service-' so that people can find it easily.
To make a pull request to this repo, please
- Fork this repo
- Add your feature or bug fix
- Add comprehensive unit tests in my test folder
- Tag me (@jpodwys) and submit
- With this release, you must use the following releases of each of the following cache modules to avoid a conflict with
.flush():- cache-service-cache-module: >= 1.0.0
- cache-service-node-cache: >= 1.0.1
- cache-service-redis: >= 1.0.1
- The default configuration returns! And this time, it's better than ever. (Not really a breaking change, but worth noting, since I removed this feature in
1.1.0). My goal was to accomidate two user groups:- The ones who want zero bloat--don't bundle cache modules I'm not going to use
- The ones who know nothing about external cache modules and just want to get caching
In order to satisfy both groups, I built a brand new, bare-bones, in-memory cache module called cacheModule. It has no external dependencies and matches
cache-service's complete API. Unminified and with comments, the module's JavaScript file is 165 lines. It will be injected intocacheService.cachesif nocacheModulesconstructor param is provided.
- cache-service has become more flexible and light-weight by no longer including cache modules directly within this repo. This means that you must now add any cache modules you want to use to your package.json and require and instantiate them yourself. cache-service will no longer accept a
cacheModuleConfigobject as the second param in its constructor. That object has been replaced with thecacheModulesarray which is an array of pre-instantiated cache modules. These changes make it so that your app need not include cache modules you will not use. Thanks @nickdaugherty for the suggestion. - As a result of the above information, cache-service makes no assumptions and therefore provides you with no default configuration. This means that you must provide a cache module in the
cacheModulesarray or cache-service will throw an exception. - For the sake of brevity,
cacheService.cacheCollectionis nowcacheService.caches.
cache-service stores its caches in a top-level property called cacheCollection. Older versions of cacheCollection contained two arrays (preApi and postApi). In version 1.0.0, cacheCollection has been simplified by eliminating its preApi and postApi properties. This means that if you have any advanced references such as cacheService.cacheCollection.preApi[0], you can simplify them to cacheService.cacheCollection[0].
Prior to this version, a complete .mget() miss (meaning that zero of the passed keys were found) returned null. Starting with this version, the same scenario returns an empty object.