From 8a8fe80ac23a993514cc2e99a516ba6dcb5c89d2 Mon Sep 17 00:00:00 2001
From: Gianluca <gianlucazuccarelli@gmail.com>
Date: Tue, 23 Jun 2020 12:03:41 +0100
Subject: [PATCH] docs: document support for paginated cache updates

---
 docs/ref-cache.md | 39 ++++++++++++++++++++++++++++++++++++---
 1 file changed, 36 insertions(+), 3 deletions(-)

diff --git a/docs/ref-cache.md b/docs/ref-cache.md
index b055c7c82..f8a37b8e4 100644
--- a/docs/ref-cache.md
+++ b/docs/ref-cache.md
@@ -76,9 +76,28 @@ const options = createMutationOptions(mutationOptions);
 apolloClient.mutate(options);
 ```
 
-> NOTE: Cache helpers currently support only GraphQL Queries that return arrays.
-> For example `getUsers():[User]`.
-> When working with single objects returned by Queries we usually do not need use any helper as Query will be updated automatically on every update
+### Pagination and relationships
+
+It may be necessary to update a field within the query and not the entire query, for example with relationships. In order to do this, it is necessary to provide the name of the field being updated with the `returnField` parameter.
+
+```javascript
+const mutationOptions = {
+  mutation: ADD_COMMENT,
+  variables: {
+    title: 'comment title'
+  },
+  updateQuery: {
+    query: GET_TASK,
+    variables: {
+      filterBy: 'some filter'
+    }
+  },
+  returnType: 'Comment',
+  operationType: CacheOperation.ADD,
+  idField: 'id',
+  returnField: 'comments
+};
+```
 
 ## Subscription Helpers
 
@@ -121,6 +140,20 @@ query.subscribeToMore(subscriptionOptions);
 
 The cache will now be kept up to date with automatic data deduplication being performed.
 
+### Pagination and relationships
+
+Similarly to the mutation cache update helpers, it is necessary to provide the `returnField` parameter to specify the name of the field to update within the query.
+
+```javascript
+export const editSubscriptionOptions = createSubscriptionOptions({
+  subscriptionQuery: NEW_COMMENT,
+  cacheUpdateQuery: GET_TASK,
+  operationType: CacheOperation.ADD,
+  idField: 'id',
+  returnField: 'comments'
+});
+```
+
 ### Multiple Subscriptions
 
 `offix-cache` also provides the ability to automatically call `subscribeToMore` on your `ObservableQuery`. This can be useful in a situation where you may have multiple subscriptions which can affect one single query. For example, if you have a `TaskAdded`, `TaskDeleted` and a `TaskUpdated` subscription you would need three separate `subscribeToMore` function calls. This can become tedious as your number of subscriptions grow. To combat this, we can use the `subscribeToMoreHelper` function from offix-cache to automatically handle this for us by passing it an array of subscriptions and their corresponding queries which need to be updated.