docs: extend manual cache management by upsertQueryData description and example

(cherry picked from commit 86b8f71)

Author: KMNowak

docs/rtk-query/usage/manual-cache-updates.mdx

@@ -3,7 +3,7 @@ id: manual-cache-updates
 title: Manual Cache Updates
 sidebar_label: Manual Cache Updates
 hide_title: true
-description: 'RTK Query > Usage > Manual Cache Updates: Updating cached data manually'
+description: 'RTK Query > Usage > Manual Cache Updates: Updating and creating cached data manually'
 ---
 
  
@@ -19,30 +19,51 @@ when it has been told that a mutation has occurred which would cause its data to
 In most cases, we recommend using `automated re-fetching` as a preference over `manual cache updates`,
 unless you encounter the need to do so.
 
-However, in some cases, you may want to update the cache manually. When you wish to update cache
-data that _already exists_ for query endpoints, you can do so using the
-[`updateQueryData`](../api/created-api/api-slice-utils.mdx#updatequerydata) thunk action
-available on the `util` object of your created API.
+However, in some cases when refetch is not necessary, you may wish to update the cache data manually.
+You can do it using provided by created API `util` object methods for both:
+
+- updating already existing cache entries with [`updateQueryData`](../api/created-api/api-slice-utils.mdx#updatequerydata)
+- creating new or replacing existing cache entries with [`upsertQueryData`](../api/created-api/api-slice-utils.mdx#upsertquerydata)
 
 Anywhere you have access to the `dispatch` method for the store instance, you can dispatch the
 result of calling `updateQueryData` in order to update the cache data for a query endpoint,
-if the corresponding cache entry exists.
+if the corresponding cache entry exists or `upsertQueryData` to create new or replace existing one.
 
-Use cases for manual cache updates include:
+### Updating existing cache entries
+For updates of existing cache entries use [`updateQueryData`](../api/created-api/api-slice-utils.mdx#updatequerydata).
 
-- Providing immediate feedback to the user when a mutation is attempted
-- After a mutation, updating a single item in a large list of items that is already cached,
-  rather than re-fetching the whole list
-- Debouncing a large number of mutations with immediate feedback as though they are being
-  applied, followed by a single request sent to the server to update the debounced attempts
-
-:::note
 `updateQueryData` is strictly intended to perform _updates_ to existing cache entries,
 not create new entries. If an `updateQueryData` thunk action is dispatched that corresponds to
 no existing cache entry for the provided `endpointName` + `args` combination, the provided `recipe`
 will not be called, and no `patches` or `inversePatches` will be returned.
+
+Use cases for manual update of cache entries:
+- Providing immediate feedback to the user when a mutation is attempted
+- After a mutation, updating a single item in a large list of items that is already cached,
+rather than re-fetching the whole list
+- Debouncing a large number of mutations with immediate feedback as though they are being
+applied, followed by a single request sent to the server to update the debounced attempts
+
+### Creating new cache entries or replacing existing ones
+To create or replace existing cache entries use [`upsertQueryData`](../api/created-api/api-slice-utils.mdx#upsertquerydata).
+
+`upsertQueryData` is intended to perform _replacements_ to existing cache entries or _creation_ of new ones.
+Due to the fact, that in `upsertQueryData` we do not have access to the previous state of the cache entry, since it can not exist yet,
+the update may be performed only as a replacement. On the contrary, `updateQueryData` allows to perform a patching of the existing cache entry, but
+can not create a new one.
+
+:::tip
+
+Manual creation of cache entries can introduce significant improvement in application performance and UX. Thanks to using the data we are already
+aware of, we can avoid unnecessary requests and loaders.
+
 :::
 
+Use cases for upserting cache entries in pair with [pessimistic updates]((../usage/manual-cache-updates.mdx#pessimistic-updates)):
+- you create a new Post and backend returns its complete data including `id`. Then we
+  can use `upsertQueryData` to create a new cache entry for the `getPostById(id)` query, preventing unnecessary fetching it on enter.
+- same can be applied for batch creations of items, when backend returns a list of created items with their ids.
+
 ## Recipes
 
 ### Optimistic Updates
@@ -57,7 +78,7 @@ The core concepts for an optimistic update are:
 - when you start a query or mutation, `onQueryStarted` will be executed
 - you manually update the cached data by dispatching `api.util.updateQueryData` within `onQueryStarted`
 - then, in the case that `queryFulfilled` rejects:
-  - you roll it back via the `.undo` property of the object you got back from the earlier dispatch,  
+  - you roll it back via the `.undo` property of the object you got back from the earlier dispatch,
     OR
   - you invalidate the cache data via `api.util.invalidateTags` to trigger a full re-fetch of the data
 
@@ -158,6 +179,8 @@ The core concepts for a pessimistic update are:
   server in the `data` property
 - you manually update the cached data by dispatching `api.util.updateQueryData` within
   `onQueryStarted`, using the data in the response from the server for your draft updates
+- you manually create a new cache entry by dispatching `api.util.upsertQueryData` within `onQueryStarted`,
+  using the complete Post object returned by backend.
 
 ```ts title="Pessimistic update mutation example (async await)"
 // file: types.ts noEmit
@@ -199,6 +222,23 @@ const api = createApi({
       },
       // highlight-end
     }),
+    createPost: build.mutation<Post, Pick<Post, 'id'> & Partial<Post>>({
+      query: ({ id, ...body }) => ({
+        url: `post/${id}`,
+        method: 'POST',
+        body,
+      }),
+      // highlight-start
+      async onQueryStarted({ id }, { dispatch, queryFulfilled }) {
+        try {
+          const { data: createdPost } = await queryFulfilled
+          const patchResult = dispatch(
+            api.util.upsertQueryData('getPost', id, createdPost)
+          )
+        } catch {}
+      },
+      // highlight-end
+    }),
   }),
 })
 ```