Add applyUpdate method to add a mutation to the store without committ…

…ing it

docs/APIReference-Store.md

@@ -20,6 +20,12 @@ The Relay `Store` provides an API for dispatching mutations to the server.
       Initiate processing of a mutation.
     </a>
   </li>
+  <li>
+    <a href="#applyupdate-static-method">
+      <pre>static applyUpdate(mutation, callbacks)</pre>
+      Adds a MutationTransaction to the queue without committing it.
+    </a>
+  </li>
 </ul>
 
 ## Methods
@@ -28,7 +34,7 @@ The Relay `Store` provides an API for dispatching mutations to the server.
 
 ```
 static update(mutation: RelayMutation, callbacks: {
-  onFailure?: (transaction: Transaction) => void;
+  onFailure?: (transaction: RelayMutationTransaction) => void;
   onSuccess?: (response: Object) => void;
 }): void
 
@@ -62,3 +68,36 @@ var mutation = new MyMutation({...});
 
 Relay.Store.update(mutation, {onFailure, onSuccess});
 ```
+
+### applyUpdate (static method)
+
+```
+static applyUpdate(mutation: RelayMutation, callbacks: {
+  onFailure?: (transaction: RelayMutationTransaction) => void;
+  onSuccess?: (response: Object) => void;
+}): RelayMutationTransaction
+```
+
+The `applyUpdate` adds a mutation just like `update`, but does not commit it. It returns a `RelayMutationTransaction` that can be committed or rollbacked.
+
+When the transaction is committed and the response is received from the server, one of the callbacks is invoked:
+  - `onSuccess` is called if the mutation succeeded.
+  - `onFailure` is called if the mutation failed.
+
+
+#### Example
+
+```
+var onSuccess = () => {
+  console.log('Mutation successful!');
+};
+var onFailure = (transaction) => {
+  var error = transaction.getError() || new Error('Mutation failed.');
+  console.error(error);
+};
+var mutation = new MyMutation({...});
+
+var transaction = Relay.Store.applyUpdate(mutation, {onFailure, onSuccess});
+
+transaction.commit();
+```

src/store/RelayStore.js

@@ -161,15 +161,21 @@ var RelayStore = {
     return new RelayQueryResultObservable(storeData, fragmentPointer);
   },
 
-  update(
+  applyUpdate(
     mutation: RelayMutation,
     callbacks?: RelayMutationTransactionCommitCallbacks
-  ): void {
-    var transaction = storeData.getMutationQueue().createTransaction(
+  ): RelayMutationTransaction {
+    return storeData.getMutationQueue().createTransaction(
       mutation,
       callbacks
     );
-    transaction.commit();
+  },
+
+  update(
+    mutation: RelayMutation,
+    callbacks?: RelayMutationTransactionCommitCallbacks
+  ): void {
+    this.applyUpdate(mutation, callbacks).commit();
   },
 };
 

src/store/__tests__/RelayStore-test.js

@@ -21,6 +21,9 @@ var Relay = require('Relay');
 var RelayQueryResultObservable = require('RelayQueryResultObservable');
 var RelayStoreData = require('RelayStoreData');
 var readRelayQueryData = require('readRelayQueryData');
+var RelayMutation = require('RelayMutation');
+var RelayMutationTransaction = require('RelayMutationTransaction');
+var RelayMutationQueue = require('RelayMutationQueue');
 
 describe('RelayStore', () => {
   var RelayStore;
@@ -149,4 +152,41 @@ describe('RelayStore', () => {
       });
     });
   });
+
+  describe('update functions', () => {
+    var mockMutation, createTransactionMock, mockTransaction, mockCallbacks;
+
+    beforeEach(() => {
+      mockTransaction = new RelayMutationTransaction();
+      mockTransaction.commit = jest.genMockFunction();
+      createTransactionMock = jest.genMockFunction();
+      createTransactionMock.mockReturnValue(mockTransaction)
+      RelayMutationQueue.prototype.createTransaction = createTransactionMock;
+      mockMutation = new RelayMutation();
+      mockCallbacks = jest.genMockFunction();
+    });
+
+    describe('applyUpdate', () => {
+      it('creates a new RelayMutationTransaction without committing it', () => {
+        let transaction = RelayStore.applyUpdate(mockMutation, mockCallbacks);
+        expect(createTransactionMock).toBeCalledWith(
+          mockMutation,
+          mockCallbacks
+        );
+        expect(mockTransaction.commit).not.toBeCalled();
+      });
+    });
+
+    describe('update', () => {
+      it('creates a new RelayMutationTransaction and commits it', () => {
+        RelayStore.update(mockMutation, mockCallbacks);
+        expect(createTransactionMock).toBeCalledWith(
+          mockMutation,
+          mockCallbacks
+        );
+        expect(mockTransaction.commit).toBeCalled();
+      });
+    });
+
+  });
 });