Add ability to provide custom cache instance

The desire for implementation details specific to caches comes up regularly (#6, #13). Since Dataloader *uses* a cache rather than implements one, allowing for a choose-your-own-cache allows for the greatest flexibility.

Still, the default will be a simple boundless cache, as most uses of DataLoader are in the context of a single request.

Author: leebyron

README.md

@@ -155,6 +155,9 @@ Create a new `DataLoader` given a batch loading function and options.
     Defaults to `key => key`. Useful to provide when JavaScript objects are keys
     and two similarly shaped objects should be considered equivalent.
 
+  - *cacheMap*: An instance of [Map][] (or an object with a similar API) to be
+    used as the underlying cache for this loader. Default `new Map()`.
+
 ##### `load(key)`
 
 Loads a key, returning a `Promise` for the value represented by that key.
@@ -279,6 +282,16 @@ This provides a single value to pass around to code which needs to perform
 data loading, such as part of the `rootValue` in a [graphql-js][] request.
 
 
+## Custom Caches
+
+DataLoader can optionaly be provided a custom Map instance to use as its
+cache. More specifically, any object that implements the methods `get()`,
+`set()`, `delete()` and `clear()` can be provided. This allows for custom Maps
+which implement various [cache algorithms][] to be provided. By default,
+DataLoader uses the standard [Map][] which simply grows until the DataLoader
+is released.
+
+
 ## Common Back-ends
 
 Looking to get started with a specific back-end? Try these example loaders:
@@ -397,7 +410,9 @@ Promise.all([ promise1, promise2 ]).then(([ user1, user2]) => {
 
 
 [@schrockn]: https://github.com/schrockn
+[Map]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map
 [graphql-js]: https://github.com/graphql/graphql-js
+[cache algorithms]: https://en.wikipedia.org/wiki/Cache_algorithms
 [express]: http://expressjs.com/
 [babel/polyfill]: https://babeljs.io/docs/usage/polyfill/
 [node_redis]: https://github.com/NodeRedis/node_redis

src/__tests__/dataloader-test.js

@@ -468,6 +468,80 @@ describe('Accepts options', () => {
 
   });
 
+  describe('Accepts custom cacheMap instance', () => {
+
+    class SimpleMap {
+      stash: Object;
+
+      constructor() {
+        this.stash = {};
+      }
+      get(key) {
+        return this.stash[key];
+      }
+      set(key, value) {
+        this.stash[key] = value;
+      }
+      delete(key) {
+        delete this.stash[key];
+      }
+      clear() {
+        this.stash = {};
+      }
+    }
+
+    it('Accepts a custom cache map implementation', async () => {
+      var aCustomMap = new SimpleMap();
+      var identityLoadCalls = [];
+      var identityLoader = new DataLoader(keys => {
+        identityLoadCalls.push(keys);
+        return Promise.resolve(keys);
+      }, { cacheMap: aCustomMap });
+
+      // Fetches as expected
+
+      var [ valueA, valueB1 ] = await Promise.all([
+        identityLoader.load('a'),
+        identityLoader.load('b'),
+      ]);
+
+      expect(valueA).to.equal('a');
+      expect(valueB1).to.equal('b');
+
+      expect(identityLoadCalls).to.deep.equal([ [ 'a', 'b' ] ]);
+      expect(Object.keys(aCustomMap.stash)).to.deep.equal([ 'a', 'b' ]);
+
+      var [ valueC, valueB2 ] = await Promise.all([
+        identityLoader.load('c'),
+        identityLoader.load('b'),
+      ]);
+
+      expect(valueC).to.equal('c');
+      expect(valueB2).to.equal('b');
+
+      expect(identityLoadCalls).to.deep.equal([ [ 'a', 'b' ], [ 'c' ] ]);
+      expect(Object.keys(aCustomMap.stash)).to.deep.equal([ 'a', 'b', 'c' ]);
+
+      // Supports clear
+
+      identityLoader.clear('b');
+      var valueB3 = await identityLoader.load('b');
+
+      expect(valueB3).to.equal('b');
+      expect(identityLoadCalls).to.deep.equal(
+        [ [ 'a', 'b' ], [ 'c' ], [ 'b' ] ]
+      );
+      expect(Object.keys(aCustomMap.stash)).to.deep.equal([ 'a', 'c', 'b' ]);
+
+      // Supports clear all
+
+      identityLoader.clearAll();
+
+      expect(Object.keys(aCustomMap.stash)).to.deep.equal([]);
+    });
+
+  });
+
 });
 
 describe('It is resilient to job queue ordering', () => {

src/index.js

@@ -12,10 +12,19 @@
 // of values or Errors.
 type BatchLoadFn<K, V> = (keys: Array<K>) => Promise<Array<V | Error>>
 
-// Optionally turn off batching or caching or provide a cache key function.
-type Options = {
+type CacheMap<K, V> = {
+  get(key: K): V | void;
+  set(key: K, value: V): any;
+  delete(key: K): any;
+  clear(): any;
+}
+
+// Optionally turn off batching or caching or provide a cache key function or a
+// custom cache instance.
+type Options<K, V> = {
   batch?: boolean,
   cache?: boolean,
+  cacheMap?: CacheMap<K, Promise<V>>,
   cacheKeyFn?: (key: any) => any
 }
 
@@ -32,7 +41,7 @@ type Options = {
 export default class DataLoader<K, V> {
   constructor(
     batchLoadFn: BatchLoadFn<K, V>,
-    options?: Options
+    options?: Options<K, V>
   ) {
     if (typeof batchLoadFn !== 'function') {
       throw new TypeError(
@@ -42,14 +51,14 @@ export default class DataLoader<K, V> {
     }
     this._batchLoadFn = batchLoadFn;
     this._options = options;
-    this._promiseCache = new Map();
+    this._promiseCache = options && options.cacheMap || new Map();
     this._queue = [];
   }
 
   // Private
   _batchLoadFn: BatchLoadFn<K, V>;
-  _options: ?Options;
-  _promiseCache: Map<K, Promise<V>>;
+  _options: ?Options<K, V>;
+  _promiseCache: CacheMap<K, Promise<V>>;
   _queue: LoaderQueue<K, V>;
 
   /**