feat($cacheFactory): cache.put now returns the added value

This allows common programming patterns to be expressed with more
concise code.

See #1583 for code examples.

src/ng/cacheFactory.js

@@ -14,7 +14,7 @@
  * @returns {object} Newly created cache object with the following set of methods:
  *
  * - `{object}` `info()` — Returns id, size, and options of cache.
- * - `{void}` `put({string} key, {*} value)` — Puts a new key-value pair into the cache.
+ * - `{{*}}` `put({string} key, {*} value)` — Puts a new key-value pair into the cache and returns it.
  * - `{{*}}` `get({string} key)` — Returns cached value for `key` or undefined for cache miss.
  * - `{void}` `remove({string} key)` — Removes a key-value pair from the cache.
  * - `{void}` `removeAll()` — Removes all cached values.
@@ -53,6 +53,8 @@ function $CacheFactoryProvider() {
           if (size > capacity) {
             this.remove(staleEnd.key);
           }
+
+          return value;
         },
 
 

test/ng/cacheFactorySpec.js

@@ -104,6 +104,12 @@ describe('$cacheFactory', function() {
         cache.remove(123);
         expect(cache.info().size).toBe(0);
       }));
+
+
+      it("should return value from put", inject(function($cacheFactory) {
+        var obj = {};
+        expect(cache.put('k1', obj)).toBe(obj);
+      }));
     });