From 7ff4b937e3803350b72a7f2f4d96e45334dc3f49 Mon Sep 17 00:00:00 2001 From: Lenz Weber-Tronic Date: Mon, 6 Feb 2023 21:46:31 +0100 Subject: [PATCH] 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 --------- Co-authored-by: Jerel Miller Co-authored-by: Alessia Bellisario --- docs/source/api/cache/InMemoryCache.mdx | 4 ++++ docs/source/caching/cache-interaction.mdx | 2 ++ 2 files changed, 6 insertions(+) diff --git a/docs/source/api/cache/InMemoryCache.mdx b/docs/source/api/cache/InMemoryCache.mdx index ebff5868fa4..d84de0ae44c 100644 --- 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 index fa6ffc078c6..05ffbbd8de0 100644 --- 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.