Merge branch 'release/0.1.0' into develop

Author: BryanDonovan

History.md

@@ -1,3 +1,7 @@
+- 0.1.0 2013-10-13
+  Removing built-in Redis store to emphasize that you should plug in your own
+  cache store.
+
 - 0.0.5 2013-10-13
   Removing hiredis requirement.
 

Makefile

@@ -20,6 +20,7 @@ test-cov: cover check-coverage
 lint:
 	./node_modules/.bin/jshint ./lib --config $(BASE)/.jshintrc && \
 	./node_modules/.bin/jshint ./test --config $(BASE)/.jshintrc
+	./node_modules/.bin/jshint ./examples --config $(BASE)/.jshintrc
 
 
 .PHONY: test

README.md

@@ -22,19 +22,20 @@ priority cache(s) first.
 
 ## Overview
 
-First, node-cache-manager features the standard functions you'd expect in most caches:
+First, it includes a `wrap` function that lets you wrap any function in cache.
+(Note, this was inspired by [node-caching](https://github.com/mape/node-caching).)
+
+Second, node-cache-manager features a built-in memory cache (using [node-lru-cache](https://github.com/isaacs/node-lru-cache)),
+with the standard functions you'd expect in most caches:
 
     set(key, val, cb)
     get(key, cb)
     del(key, cb)
 
-Second, it includes a `wrap` function that lets you wrap any function in cache.
-(Note, this was inspired by [node-caching](https://github.com/mape/node-caching).)
-
 Third, node-cache-manager lets you set up a tiered cache strategy.  This may be of
 limited use in most cases, but imagine a scenario where you expect tons of
-traffic, and don't want to hit Redis for every request.  You decide to store
-the most commonly-requested data in an in-memory cache (like [node-lru-cache](https://github.com/isaacs/node-lru-cache)),
+traffic, and don't want to hit your primary cache (like Redis) for every request.
+You decide to store the most commonly-requested data in an in-memory cache,
 perhaps with a very short timeout and/or a small data size limit.  But you
 still want to store the data in Redis for backup, and for the requests that
 aren't as common as the ones you want to store in memory. This is something
@@ -43,22 +44,24 @@ node-cache-manager handles easily and transparently.
 
 ## Usage Examples
 
+See examples below and in the examples directory.  See ``examples/redis_example`` for an example of how to implement a
+Redis cache store with connection pooling.
+
 ### Single Store
 
 ```javascript
         var cache_manager = require('cache-manager');
-        var redis_cache = cache_manager.caching({store: 'redis', db: 1, ttl: 100/*seconds*/});
         var memory_cache = cache_manager.caching({store: 'memory', max: 100, ttl: 10/*seconds*/});
 
         // Note: callback is optional in set() and del().
 
-        redis_cache.set('foo', 'bar', function(err) {
+        memory_cache.set('foo', 'bar', function(err) {
             if (err) { throw err; }
 
-            redis_cache.get('foo', function(err, result) {
+            memory_cache.get('foo', function(err, result) {
                 console.log(result);
                 // >> 'bar'
-                redis_cache.del('foo', function(err) {});
+                memory_cache.del('foo', function(err) {});
             });
         });
 
@@ -72,13 +75,13 @@ node-cache-manager handles easily and transparently.
         var user_id = 123;
         var key = 'user_' + user_id; 
 
-        redis_cache.wrap(key, function (cb) {
+        memory_cache.wrap(key, function (cb) {
             get_user(user_id, cb);
         }, function (err, user) {
             console.log(user);
 
-            // Second time fetches user from redis_cache 
-            redis_cache.wrap(key, function (cb) {
+            // Second time fetches user from memory_cache
+            memory_cache.wrap(key, function (cb) {
                 get_user(user_id, cb);
             }, function (err, user) {
                 console.log(user);
@@ -95,7 +98,7 @@ node-cache-manager handles easily and transparently.
 #### Custom Stores
 
 You can use your own custom store by creating one with the same API as the
-build-in redis and memory stores.  To use your own store, you can either pass
+build-in memory stores (such as a redis or memcached store).  To use your own store, you can either pass
 in an instance of it, or pass in the path to the module.
 
 E.g.,
@@ -110,7 +113,7 @@ E.g.,
 ### Multi-Store
 
 ```javascript
-        var multi_cache = cache_manager.multi_caching([memory_cache, redis_cache]);
+        var multi_cache = cache_manager.multi_caching([memory_cache, some_other_cache]);
         user_id2 = 456;
         key2 = 'user_' + user_id; 
 
@@ -135,7 +138,7 @@ E.g.,
 
             // Second time fetches user from memory_cache, since it's highest priority.
             // If the data expires in the memory cache, the next fetch would pull it from
-            // the Redis cache, and set the data in memory again.
+            // the 'some_other_cache', and set the data in memory again.
             multi_cache.wrap(key2, function (cb) {
                 get_user(user_id2, cb);
             }, function (err, user) {

examples/example.js

@@ -1,14 +1,17 @@
-var cache_manager = require('cache-manager');
-var redis_cache = cache_manager.caching({store: 'redis', db: 1, ttl: 100/*seconds*/});
+var cache_manager = require('../');
 var memory_cache = cache_manager.caching({store: 'memory', max: 100, ttl: 10/*seconds*/});
+var memory_cache2 = cache_manager.caching({store: 'memory', max: 100, ttl: 100/*seconds*/});
 
-redis_cache.set('foo', 'bar', function(err) {
+//
+// Basic usage
+//
+memory_cache2.set('foo', 'bar', function (err) {
     if (err) { throw err; }
 
-    redis_cache.get('foo', function(err, result) {
+    memory_cache2.get('foo', function (err, result) {
         console.log(result);
         // >> 'bar'
-        redis_cache.del('foo', function(err) {});
+        memory_cache2.del('foo', function (err) { console.log(err); });
     });
 });
 
@@ -20,15 +23,18 @@ function get_user(id, cb) {
 }
 
 var user_id = 123;
-var key = 'user_' + user_id; 
+var key = 'user_' + user_id;
 
-redis_cache.wrap(key, function (cb) {
+//
+// wrap() example 
+//
+memory_cache2.wrap(key, function (cb) {
     get_user(user_id, cb);
 }, function (err, user) {
     console.log(user);
 
-    // Second time fetches user from redis_cache 
-    redis_cache.wrap(key, function (cb) {
+    // Second time fetches user from memory_cache2 
+    memory_cache2.wrap(key, function (cb) {
         get_user(user_id, cb);
     }, function (err, user) {
         console.log(user);
@@ -41,9 +47,9 @@ redis_cache.wrap(key, function (cb) {
 // { id: 123, name: 'Bob' }
 
 
-var multi_cache = cache_manager.multi_caching([memory_cache, redis_cache]);
-user_id2 = 456;
-key2 = 'user_' + user_id; 
+var multi_cache = cache_manager.multi_caching([memory_cache, memory_cache2]);
+var user_id2 = 456;
+var key2 = 'user_' + user_id;
 
 multi_cache.wrap(key2, function (cb) {
     get_user(user_id2, cb);
@@ -60,16 +66,17 @@ multi_cache.wrap(key2, function (cb) {
     });
 
     // Sets in all caches.
-    multi_cache.set('foo2', 'bar2', function(err) {
+    multi_cache.set('foo2', 'bar2', function (err) {
         if (err) { throw err; }
 
         // Fetches from highest priority cache that has the key.
-        multi_cache.get('foo2', function(err, result) {
+        multi_cache.get('foo2', function (err, result) {
             console.log(result);
             // >> 'bar2'
 
             // Delete from all caches
-            multi_cache.del('foo2', function(err) {
+            multi_cache.del('foo2', function (err) {
+                console.log(err);
                 process.exit();
             });
         });

examples/redis_example/example.js

@@ -0,0 +1,47 @@
+// Setup:
+// npm install redis
+// npm install sol-redis-pool
+
+var cache_manager = require('../../');
+var redis_store = require('./redis_store');
+var redis_cache = cache_manager.caching({store: redis_store, db: 0, ttl: 100/*seconds*/});
+
+redis_cache.set('foo', 'bar', function (err) {
+    if (err) { throw err; }
+
+    redis_cache.get('foo', function (err, result) {
+        console.log(result);
+        // >> 'bar'
+        redis_cache.del('foo', function (err) { console.log(err); });
+    });
+});
+
+function get_user(id, cb) {
+    setTimeout(function () {
+        console.log("Returning user from slow database.");
+        cb(null, {id: id, name: 'Bob'});
+    }, 100);
+}
+
+var user_id = 123;
+var key = 'user_' + user_id;
+
+redis_cache.wrap(key, function (cb) {
+    get_user(user_id, cb);
+}, function (err, user) {
+    console.log(user);
+
+    // Second time fetches user from redis_cache 
+    redis_cache.wrap(key, function (cb) {
+        get_user(user_id, cb);
+    }, function (err, user) {
+        console.log(user);
+    });
+});
+
+// Outputs:
+// Returning user from slow database.
+// { id: 123, name: 'Bob' }
+// { id: 123, name: 'Bob' }
+
+process.exit();

examples/redis_example/redis_store.js

@@ -0,0 +1,86 @@
+/**
+ * This is a very basic example of how you can implement your own Redis-based
+ * cache store with connection pooling.
+ */
+
+var RedisPool = require('sol-redis-pool');
+
+function redis_store(args) {
+    args = args || {};
+    var self = {};
+    var ttl = args.ttl;
+    self.name = 'redis';
+    self.client = require('redis').createClient(args.port, args.host, args);
+
+    var redis_options = {
+        redis_host: args.host || '127.0.0.1',
+        redis_port: args.port || 6379
+    };
+
+    var pool = new RedisPool(redis_options);
+
+    function connect(cb) {
+        pool.acquire(function (err, conn) {
+            if (err) {
+                pool.release(conn);
+                return cb(err);
+            }
+
+            if (args.db || args.db === 0) {
+                conn.select(args.db);
+            }
+
+            cb(null, conn);
+        });
+    }
+
+    self.get = function (key, cb) {
+        connect(function (err, conn) {
+            if (err) { return cb(err); }
+
+            conn.get(key, function (err, result) {
+                if (err) { pool.release(conn); return cb(err); }
+                cb(null, JSON.parse(result));
+            });
+        });
+    };
+
+    self.set = function (key, value, cb) {
+        connect(function (err, conn) {
+            if (err) { return cb(err); }
+
+            if (ttl) {
+                conn.setex(key, ttl, JSON.stringify(value), function (err, result) {
+                    pool.release(conn);
+                    cb(err, result);
+                });
+            } else {
+                conn.set(key, JSON.stringify(value), function (err, result) {
+                    pool.release(conn);
+                    cb(err, result);
+                });
+            }
+        });
+    };
+
+    self.del = function (key, cb) {
+        connect(function (err, conn) {
+            if (err) { return cb(err); }
+
+            conn.del(key, function (err, result) {
+                pool.release(conn);
+                cb(err, result);
+            });
+        });
+    };
+
+    return self;
+}
+
+var methods = {
+    create: function (args) {
+        return redis_store(args);
+    }
+};
+
+module.exports = methods;