From 9a391cc052446c70b5dfd5c6a846bff2ddfc35fc Mon Sep 17 00:00:00 2001
From: Guillaume Chau <guillaume.b.chau@gmail.com>
Date: Mon, 2 May 2022 18:24:02 +0200
Subject: [PATCH] docs: cache updates, fix #1186

---
 .../docs/src/guide-components/mutation.md     | 39 +++++++----
 .../docs/src/guide-composable/mutation.md     | 64 +++++++++++++------
 packages/docs/src/guide-option/mutations.md   | 10 ++-
 3 files changed, 76 insertions(+), 37 deletions(-)

diff --git a/packages/docs/src/guide-components/mutation.md b/packages/docs/src/guide-components/mutation.md
index 59886ae..2cf47d9 100644
--- a/packages/docs/src/guide-components/mutation.md
+++ b/packages/docs/src/guide-components/mutation.md
@@ -106,9 +106,18 @@ export default {
         },
       }
       // Read the query from cache
-      const data = store.readQuery(query)
-      // Mutate cache result
-      data.thread.messages.push(sendMessageToThread.message)
+      let data = store.readQuery(query)
+      // Change cache result
+      data = {
+        ...data,
+        thread: {
+          ...data.thread,
+          messages: [
+            ...data.thread.messages,
+            sendMessageToThread.message
+          ],
+        },
+      }
       // Write back to the cache
       store.writeQuery({
         ...query,
@@ -191,18 +200,20 @@ export default {
         },
       }
       // Read the query from cache
-      const data = store.readQuery(query)
-      // Look for the deleted item
-      const index = data.thread.messages.findIndex(m => m.id === this.messageId)
-      if (index !== -1) {
-        // Mutate cache result
-        data.thread.messages.splice(index, 1)
-        // Write back to the cache
-        store.writeQuery({
-          ...query,
-          data,
-        })
+      let data = store.readQuery(query)
+      // Change cache result
+      data = {
+        ...data,
+        thread: {
+          ...data.thread,
+          messages: data.thread.messages.filter(m => m.id !== this.messageId),
+        },
       }
+      // Write back to the cache
+      store.writeQuery({
+        ...query,
+        data,
+      })
     },
   }
 }
diff --git a/packages/docs/src/guide-composable/mutation.md b/packages/docs/src/guide-composable/mutation.md
index 99b62d6..7d56c34 100644
--- a/packages/docs/src/guide-composable/mutation.md
+++ b/packages/docs/src/guide-composable/mutation.md
@@ -307,11 +307,11 @@ In this example, if we already loaded the list of messages containing the one wi
 
 If a mutation modifies multiple entities, or if it creates or deletes one or many entities, the Apollo Client will *not* automatically update the cache to reflect the changes made by the mutation. Instead, you should update the cache using an `update` function in the options.
 
-The purpose of this `update` function is to modify your cached data to match the changes made by the mutation on the server.
+The purpose of this `update` function is to modify your cached data to match the changes made by the mutation on the server. Note that Apollo cache data is immutable so you need to either use the `...` (spread) operator or deeply clone the cached data before modifying it.
 
 For example, our `sendMessage` mutation should add the new message to our cache:
 
-```vue{33-37}
+```vue{33-43}
 <script>
 import { useQuery, useResult, useMutation } from '@vue/apollo-composable'
 import gql from 'graphql-tag'
@@ -345,8 +345,14 @@ export default {
         text: newMessage.value,
       },
       update: (cache, { data: { sendMessage } }) => {
-        const data = cache.readQuery({ query: MESSAGES })
-        data.messages.push(sendMessage)
+        let data = cache.readQuery({ query: MESSAGES })
+        data = {
+          ...data,
+          messages: [
+            ...data.messages,
+            sendMessage,
+          ],
+        }
         cache.writeQuery({ query: MESSAGES, data })
       },
     }))
@@ -378,7 +384,7 @@ export default {
 
 Let's focus on the mutation:
 
-```js{12-16}
+```js{12-22}
 const { mutate: sendMessage } = useMutation(gql`
   mutation sendMessage ($text: String!) {
     sendMessage (text: $text) {
@@ -391,8 +397,14 @@ const { mutate: sendMessage } = useMutation(gql`
     text: newMessage.value,
   },
   update: (cache, { data: { sendMessage } }) => {
-    const data = cache.readQuery({ query: MESSAGES })
-    data.messages.push(sendMessage)
+    let data = cache.readQuery({ query: MESSAGES })
+    data = {
+      ...data,
+      messages: [
+        ...data.messages,
+        sendMessage,
+      ],
+    }
     cache.writeQuery({ query: MESSAGES, data })
   },
 }))
@@ -406,7 +418,7 @@ After the `update` function is called, the components whose data has been change
 
 Alternatively, we can pass an `update` function within the second parameter when calling the `mutate`  function:
 
-```js{14-20}
+```js{14-24}
 const { mutate: sendMessage } = useMutation(gql`
   mutation sendMessage ($text: String!) {
     sendMessage (text: $text) {
@@ -416,18 +428,22 @@ const { mutate: sendMessage } = useMutation(gql`
   }
 `)
 
-sendMessage(
-  {
-    text: text.value
-  },
-  {
-    update: (cache, { data: { sendMessage } }) => {
-      const data = cache.readQuery({ query: MESSAGES });
-      data.messages.push(sendMessage);
-      cache.writeQuery({ query: MESSAGES, data });
+sendMessage({
+  text: text.value
+},
+{
+  update: (cache, { data: { sendMessage } }) => {
+    let data = cache.readQuery({ query: MESSAGES })
+    data = {
+      ...data,
+      messages: [
+        ...data.messages,
+        sendMessage,
+      ],
     }
+    cache.writeQuery({ query: MESSAGES, data })
   }
-);
+})
 ```
 
 ## Mutation state
@@ -480,7 +496,7 @@ onDone(result => {
 
 In our example, this is very useful for resetting the message input:
 
-```vue{22,40-42,55}
+```vue{22,46-48}
 <script>
 import { useQuery, useResult, useMutation } from '@vue/apollo-composable'
 import gql from 'graphql-tag'
@@ -514,8 +530,14 @@ export default {
         text: newMessage.value,
       },
       update: (cache, { data: { sendMessage } }) => {
-        const data = cache.readQuery({ query: MESSAGES })
-        data.messages.push(sendMessage)
+        let data = cache.readQuery({ query: MESSAGES })
+        data = {
+          ...data,
+          messages: [
+            ...data.messages,
+            sendMessage,
+          ],
+        }
         cache.writeQuery({ query: MESSAGES, data })
       },
     }))
diff --git a/packages/docs/src/guide-option/mutations.md b/packages/docs/src/guide-option/mutations.md
index 6b85ca7..eb9b036 100644
--- a/packages/docs/src/guide-option/mutations.md
+++ b/packages/docs/src/guide-option/mutations.md
@@ -35,9 +35,15 @@ methods: {
       // and then with the real result of the mutation
       update: (store, { data: { addTag } }) => {
         // Read the data from our cache for this query.
-        const data = store.readQuery({ query: TAGS_QUERY })
+        let data = store.readQuery({ query: TAGS_QUERY })
         // Add our tag from the mutation to the end
-        data.tags.push(addTag)
+        data = {
+          ...data,
+          tags: [
+            ...data.tags,
+            addTag,
+          ],
+        }
         // Write our data back to the cache.
         store.writeQuery({ query: TAGS_QUERY, data })
       },