Add note discussing immutability to update* docs (#10522)

* Add note discussing immutability to `update*` docs * Apply suggestions from code review Co-authored-by: Jerel Miller <[email protected]> --------- Co-authored-by: Jerel Miller <[email protected]> Co-authored-by: Alessia Bellisario <[email protected]>
apollographql · Feb 6, 2023 · 7ff4b93 · 7ff4b93
1 parent 015a1ff
commit 7ff4b93
Show file tree

Hide file tree

Showing 2 changed files with 6 additions and 0 deletions.
diff --git a/docs/source/api/cache/InMemoryCache.mdx b/docs/source/api/cache/InMemoryCache.mdx
@@ -433,6 +433,8 @@ The update function of `updateQuery` takes a query's current cached value and re
 
 The returned value is automatically passed to [`writeQuery`](#writequery), which modifies the cached data.
 
+Please note the `update` function has to calculate the new value in an immutable way. You can read more about immutable updates in the [React documentation](https://beta.reactjs.org/learn/updating-objects-in-state).
+
 ### Signature
 
 ```ts title="src/cache/core/cache.ts"
@@ -892,6 +894,8 @@ The update function of `updateFragment` takes a fragment's current cached value
 
 The returned value is automatically passed to [`writeFragment`](#writefragment), which modifies the cached data.
 
+Please note the `update` function has to calculate the new value in an immutable way. You can read more about immutable updates in the [React documentation](https://beta.reactjs.org/learn/updating-objects-in-state).
+
 ### Signature
 
 ```ts title="src/cache/core/cache.ts"

diff --git a/docs/source/caching/cache-interaction.mdx b/docs/source/caching/cache-interaction.mdx
@@ -269,6 +269,8 @@ Each of these methods takes two parameters:
 
 After either method fetches data from the cache, it calls its update function and passes it the cached `data`. The update function can then return a value to _replace_ that `data` in the cache. In the example above, every cached `Todo` object has its `completed` field set to `true` (and other fields remain unchanged).
 
+Please note that the replacement value has to be calculated in an immutable way. You can read more about immutable updates in [the React documentation](https://beta.reactjs.org/learn/updating-objects-in-state).
+
 If the update function shouldn't make _any_ changes to the cached data, it can return `undefined`.
 
 The update function's return value is passed to either `writeQuery` or `writeFragment`, which modifies the cached data.