Only allow priming keys that do not already exist. Update documentation

and add new tests to match.

Author: ryanspradlin

README.md

@@ -198,8 +198,9 @@ method chaining.
 
 ##### `prime(key, value)`
 
-Primes the cache with the provided key and value. If the key already exists, the
-value will be updated. Returns itself for method chaining.
+Primes the cache with the provided key and value. If the key already exists, no
+change is made. (To forcefully prime the cache, clear the key first with
+`loader.clear(key).prime(key, value)`.) Returns itself for method chaining.
 
 
 ## Using with GraphQL

src/__tests__/dataloader-test.js

@@ -181,6 +181,48 @@ describe('Primary API', () => {
     expect(loadCalls).to.deep.equal([ [ 'B' ] ]);
   });
 
+  it('does not prime keys that already exist', async () => {
+    var [ identityLoader, loadCalls ] = idLoader();
+
+    identityLoader.prime('A', 'X');
+
+    var a1 = await identityLoader.load('A');
+    var b1 = await identityLoader.load('B');
+    expect(a1).to.equal('X');
+    expect(b1).to.equal('B');
+
+    identityLoader.prime('A', 'Y');
+    identityLoader.prime('B', 'Y');
+
+    var a2 = await identityLoader.load('A');
+    var b2 = await identityLoader.load('B');
+    expect(a2).to.equal('X');
+    expect(b2).to.equal('B');
+
+    expect(loadCalls).to.deep.equal([ [ 'B' ] ]);
+  });
+
+  it('allows forcefully priming the cache', async () => {
+    var [ identityLoader, loadCalls ] = idLoader();
+
+    identityLoader.prime('A', 'X');
+
+    var a1 = await identityLoader.load('A');
+    var b1 = await identityLoader.load('B');
+    expect(a1).to.equal('X');
+    expect(b1).to.equal('B');
+
+    identityLoader.clear('A').prime('A', 'Y');
+    identityLoader.clear('B').prime('B', 'Y');
+
+    var a2 = await identityLoader.load('A');
+    var b2 = await identityLoader.load('B');
+    expect(a2).to.equal('Y');
+    expect(b2).to.equal('Y');
+
+    expect(loadCalls).to.deep.equal([ [ 'B' ] ]);
+  });
+
 });
 
 describe('Represents Errors', () => {

src/index.js

@@ -159,8 +159,8 @@ export default class DataLoader<K, V> {
   }
 
   /**
-   * Adds/updates the provied key and value in the cache. Returns itself for
-   * method chaining.
+   * Adds the provied key and value to the cache. If the key already exists, no
+   * change is made. Returns itself for method chaining.
    */
   prime(key: K, value: V): DataLoader<K, V> {
     var cacheKeyFn = this._options && this._options.cacheKeyFn;
@@ -172,7 +172,11 @@ export default class DataLoader<K, V> {
         Promise.reject(value) :
         Promise.resolve(value);
 
-    this._promiseCache.set(cacheKey, promise);
+    // Only add the key if it does not already exist.
+    if (this._promiseCache.get(cacheKey) === undefined) {
+      this._promiseCache.set(cacheKey, promise);
+    }
+
     return this;
   }
 }