Merge branch 'master' into feature/CORE-440-respect_response_cache_he…

…aders

README.md

@@ -188,15 +188,17 @@ superagent
 );
 ```
 
-## .prune(callback (response))
+## .prune(callback (response, gutResponse))
 
-> Caution: if you use this function, `supergent-cache-plugin` [will not gut](#what-exactly-gets-cached) the `response` object for you. Be sure that the result of your `.prune()` callback function will never be circular and is not larger than it needs to be.
+> Caution: if you use this function, `supergent-cache-plugin` [will not automatically gut](#what-exactly-gets-cached) the `response` object for you (although you can use the `gutResponse` param to do so manually--more on that below). Be sure that the result of your `.prune()` callback function will never be circular and is not larger than it needs to be.
 
 If you need to dig several layers into superagent's response, you can do so by passing a function to `.prune()`. Your prune function will receive superagent's response and should return a truthy value or `null`. The benefit of using this function is that you can cache only what you need.
 
+Your prune function will optionally receive `gutResponse` as its second param. This is the method that `superagent-cache-plugin` calls internally to simplify responses. If, based on some processing within the function you pass to `.prune`, you decide that no custom return value is necessary, or you would like to take advantage of the default behavior plus some of your own, you can call `gutResponse(response)` to get the value that `superagent-cache-plugin` would have returned without a call to `.prune`.
+
 #### Arguments
 
-* callback: a function that accepts superagent's response object and returns a truthy value or null
+* callback: a function that accepts superagent's response object and the gutResponse function and returns a truthy value or null
 
 #### Example
 
@@ -217,6 +219,27 @@ superagent
 );
 ```
 
+#### Example Using `gutResponse`
+
+```javascript
+var prune = function(r, gutResponse){
+  var output = gutResponse(r);
+  output.customValue = getCustomValue();
+  return output;
+}
+
+//response will now be superagent-cache-plugin's default output plus `customValue`
+//all of which will be cached rather than the entire superagent response
+superagent
+  .get(uri)
+  .use(superagentCache)
+  .prune(prune)
+  .end(function (error, response){
+    // handle response
+  }
+);
+```
+
 ## .pruneQuery(params)
 
 In the event that you need certain query params to execute a query but cannot have those params as part of your cache key (useful when security or time-related params are sent), use `.pruneQuery()` to remove those properties. Pass `.pruneQuery()` an array containing the param keys you want omitted from the cache key.

index.js

@@ -175,7 +175,7 @@ module.exports = function(cache, defaults){
                     response.redirects = _Request.scRedirectsList;
                     policy = new CachePolicy(Request.toJSON(), utils.gutResponse(response, Request));
                     if(props.prune){
-                      response = props.prune(response);
+                      response = props.prune(response, utils.gutResponse);
                     }
                     else if(props.responseProp) {
                       response = response[props.responseProp] || null;

package.json

@@ -1,14 +1,14 @@
 {
   "name": "superagent-cache-plugin",
-  "version": "2.0.0",
+  "version": "2.1.0",
   "description": "Superagent with flexible built-in caching.",
   "main": "index.js",
   "devDependencies": {
     "superagent": "3.x",
     "cache-service-cache-module": "1.x",
     "es6-promise": "3.0.2",
     "expect": "1.6.0",
-    "express": "3.4.3",
+    "express": ">=3.11.0",
     "mocha": "1.13.0",
     "mock-localstorage": "0.1.3"
   },

test/server/spec.js

@@ -5,6 +5,7 @@ var cModule = require('cache-service-cache-module');
 var cache = new cModule();
 var superagentCacheModule = require('../../index');
 var superagentCache = superagentCacheModule(cache, { expiration: 1 });
+var utils = require('../../utils');
 
 var app = express();
 
@@ -112,6 +113,22 @@ describe('superagentCache', function() {
       );
     });
 
+    it('.get() .prune(f(r, g)) .end() should expose the internal gutResponse function', function (done) {
+      var prune = function(r, gut){
+        expect(gut).toBe(utils.gutResponse);
+        return gut(r);
+      }
+      superagent
+        .get('localhost:3000/one')
+        .use(superagentCache)
+        .prune(prune)
+        .end(function (err, response, key){
+          expect(response.body.key).toBe('one');
+          done();
+        }
+      );
+    });
+
     it('.get() .responseProp() .end() should get responseProp before caching', function (done) {
       superagent
         .get('localhost:3000/one')