Document upsertQueryData

Author: markerikson

docs/rtk-query/api/created-api/api-slice-utils.mdx

@@ -13,7 +13,13 @@ The API slice object includes various utilities that can be used for cache manag
 such as implementing [optimistic updates](../../usage/manual-cache-updates.mdx#optimistic-updates),
 as well implementing [server side rendering](../../usage/server-side-rendering.mdx).
 
-These are included in a `util` field inside the slice object.
+These are included as `api.util` inside the API object.
+
+:::info
+
+Some of the TS types on this page are pseudocode to illustrate intent, as the actual internal types are fairly complex.
+
+:::
 
 ### `updateQueryData`
 
@@ -48,8 +54,7 @@ The thunk returns an object containing `{patches: Patch[], inversePatches: Patch
 
 This is typically used as the first step in implementing optimistic updates. The generated `inversePatches` can be used to revert the updates by calling `dispatch(patchQueryData(endpointName, args, inversePatches))`. Alternatively, the `undo` method can be called directly to achieve the same effect.
 
-Note that the first two arguments (`endpointName` and `args`) are used to determine which existing
-cache entry to update. If no existing cache entry is found, the `updateRecipe` callback will not run.
+Note that the first two arguments (`endpointName` and `args`) are used to determine which existing cache entry to update. If no existing cache entry is found, the `updateRecipe` callback will not run.
 
 #### Example 1
 
@@ -105,6 +110,43 @@ dispatch(api.endpoints.getPostById.initiate(1))
 dispatch(api.endpoints.getPostById.initiate(1, { ...options }))
 ```
 
+### `upsertQueryData`
+
+#### Signature
+
+```ts no-transpile
+const upsertQueryData = <T>(
+  endpointName: string,
+  args: any,
+  newEntryData: T
+) => ThunkAction<Promise<CacheEntry<T>>, PartialState, any, AnyAction>;
+```
+
+- **Parameters**
+  - `endpointName`: a string matching an existing endpoint name
+  - `args`: an argument matching that used for a previous query call, used to determine which cached dataset needs to be updated
+  - `newEntryValue`: the value to be written into the corresponding cache entry's `data` field
+
+#### Description
+
+A Redux thunk action creator that, when dispatched, acts as an artificial API request to upsert a value into the cache.
+
+The thunk action creator accepts three arguments: the name of the endpoint we are updating (such as `'getPost'`), the appropriate query arg values to construct the desired cache key, and the data to upsert.
+
+If no cache entry for that cache key exists, a cache entry will be created and the data added. If a cache entry already exists, this will _overwrite_ the existing cache entry data.
+
+The thunk executes _asynchronously_, and returns a promise that resolves when the store has been updated.
+
+If dispatched while an actual request is in progress, both the upsert and request will be handled as soon as they resolve, resulting in a "last result wins" update behavior.
+
+#### Example
+
+```ts no-transpile
+await dispatch(
+  api.util.upsertQueryData('getPost', { id: 1 }, { id: 1, text: 'Hello!' })
+)
+```
+
 ### `patchQueryData`
 
 #### Signature
@@ -124,9 +166,9 @@ const patchQueryData = (
 
 #### Description
 
-A Redux thunk action creator that applies a JSON diff/patch array to the cached data for a given query result. This immediately updates the Redux state with those changes.
+A Redux thunk action creator that, when dispatched, applies a JSON diff/patch array to the cached data for a given query result. This immediately updates the Redux state with those changes.
 
-The thunk action creator accepts three arguments: the name of the endpoint we are updating (such as `'getPost'`), any relevant query arguments, and a JSON diff/patch array as produced by Immer's `produceWithPatches`.
+The thunk action creator accepts three arguments: the name of the endpoint we are updating (such as `'getPost'`), the appropriate query arg values to construct the desired cache key, and a JSON diff/patch array as produced by Immer's `produceWithPatches`.
 
 This is typically used as the second step in implementing optimistic updates. If a request fails, the optimistically-applied changes can be reverted by dispatching `patchQueryData` with the `inversePatches` that were generated by `updateQueryData` earlier.
 

packages/toolkit/src/query/core/module.ts

@@ -229,7 +229,7 @@ declare module '../apiTypes' {
         /**
          * A Redux thunk that can be used to manually trigger pre-fetching of data.
          *
-         * The thunk accepts three arguments: the name of the endpoint we are updating (such as `'getPost'`), any relevant query arguments, and a set of options used to determine if the data actually should be re-fetched based on cache staleness.
+         * The thunk accepts three arguments: the name of the endpoint we are updating (such as `'getPost'`), the appropriate query arg values to construct the desired cache key, and a set of options used to determine if the data actually should be re-fetched based on cache staleness.
          *
          * React Hooks users will most likely never need to use this directly, as the `usePrefetch` hook will dispatch this thunk internally as needed when you call the prefetching function supplied by the hook.
          *
@@ -247,12 +247,14 @@ declare module '../apiTypes' {
         /**
          * A Redux thunk action creator that, when dispatched, creates and applies a set of JSON diff/patch objects to the current state. This immediately updates the Redux state with those changes.
          *
-         * The thunk action creator accepts three arguments: the name of the endpoint we are updating (such as `'getPost'`), any relevant query arguments, and a callback function. The callback receives an Immer-wrapped `draft` of the current state, and may modify the draft to match the expected results after the mutation completes successfully.
+         * The thunk action creator accepts three arguments: the name of the endpoint we are updating (such as `'getPost'`), the appropriate query arg values to construct the desired cache key, and an `updateRecipe` callback function. The callback receives an Immer-wrapped `draft` of the current state, and may modify the draft to match the expected results after the mutation completes successfully.
          *
-         * The thunk returns an object containing `{patches: Patch[], inversePatches: Patch[], undo: () => void}`. The `patches` and `inversePatches` are generated using Immer's [`produceWithPatches` method](https://immerjs.github.io/immer/patches).
+         * The thunk executes _synchronously_, and returns an object containing `{patches: Patch[], inversePatches: Patch[], undo: () => void}`. The `patches` and `inversePatches` are generated using Immer's [`produceWithPatches` method](https://immerjs.github.io/immer/patches).
          *
          * This is typically used as the first step in implementing optimistic updates. The generated `inversePatches` can be used to revert the updates by calling `dispatch(patchQueryData(endpointName, args, inversePatches))`. Alternatively, the `undo` method can be called directly to achieve the same effect.
          *
+         * Note that the first two arguments (`endpointName` and `args`) are used to determine which existing cache entry to update. If no existing cache entry is found, the `updateRecipe` callback will not run.
+         *
          * @example
          *
          * ```ts
@@ -272,14 +274,33 @@ declare module '../apiTypes' {
           Definitions,
           RootState<Definitions, string, ReducerPath>
         >
+        /**
+         * A Redux thunk action creator that, when dispatched, acts as an artificial API request to upsert a value into the cache.
+         *
+         * The thunk action creator accepts three arguments: the name of the endpoint we are updating (such as `'getPost'`), the appropriate query arg values to construct the desired cache key, and the data to upsert.
+         *
+         * If no cache entry for that cache key exists, a cache entry will be created and the data added. If a cache entry already exists, this will _overwrite_ the existing cache entry data.
+         *
+         * The thunk executes _asynchronously_, and returns a promise that resolves when the store has been updated.
+         *
+         * If dispatched while an actual request is in progress, both the upsert and request will be handled as soon as they resolve, resulting in a "last result wins" update behavior.
+         *
+         * @example
+         *
+         * ```ts
+         * await dispatch(
+         *   api.util.upsertQueryData('getPost', {id: 1}, {id: 1, text: "Hello!"})
+         * )
+         * ```
+         */
         upsertQueryData: UpsertQueryDataThunk<
           Definitions,
           RootState<Definitions, string, ReducerPath>
         >
         /**
          * A Redux thunk that applies a JSON diff/patch array to the cached data for a given query result. This immediately updates the Redux state with those changes.
          *
-         * The thunk accepts three arguments: the name of the endpoint we are updating (such as `'getPost'`), any relevant query arguments, and a JSON diff/patch array as produced by Immer's `produceWithPatches`.
+         * The thunk accepts three arguments: the name of the endpoint we are updating (such as `'getPost'`), the appropriate query arg values to construct the desired cache key, and a JSON diff/patch array as produced by Immer's `produceWithPatches`.
          *
          * This is typically used as the second step in implementing optimistic updates. If a request fails, the optimistically-applied changes can be reverted by dispatching `patchQueryData` with the `inversePatches` that were generated by `updateQueryData` earlier.
          *

packages/toolkit/src/query/tests/optimisticUpserts.test.tsx

@@ -182,7 +182,7 @@ describe('basic lifecycle', () => {
 })
 
 describe('upsertQueryData', () => {
-  test('updates cache values, can apply inverse patch', async () => {
+  test('inserts cache entry', async () => {
     baseQuery
       .mockResolvedValueOnce({
         id: '3',