Merge pull request #2804 from reduxjs/docs/v1.9-docs

Author: markerikson

.yarn/releases/yarn-3.1.0.cjs

@@ -2,8 +2,8 @@ nodeLinker: node-modules
 
 plugins:
   - path: .yarn/plugins/@yarnpkg/plugin-workspace-tools.cjs
-    spec: "@yarnpkg/plugin-workspace-tools"
+    spec: '@yarnpkg/plugin-workspace-tools'
   - path: .yarn/plugins/@yarnpkg/plugin-version.cjs
-    spec: "@yarnpkg/plugin-version"
+    spec: '@yarnpkg/plugin-version'
 
-yarnPath: .yarn/releases/yarn-3.1.0.cjs
+yarnPath: .yarn/releases/yarn-3.2.4.cjs

.yarn/releases/yarn-3.2.4.cjs

@@ -0,0 +1,77 @@
+---
+id: codemods
+title: Codemods
+sidebar_label: Codemods
+hide_title: true
+---
+
+ 
+
+# Codemods
+
+Per [the description in `1.9.0-alpha.0`](https://github.com/reduxjs/redux-toolkit/releases/tag/v1.9.0-alpha.0), we plan to remove the "object" argument from `createReducer` and `createSlice.extraReducers` in the future RTK 2.0 major version. In `1.9.0-alpha.0`, we added a one-shot runtime warning to each of those APIs.
+
+To simplify upgrading codebases, we've published a set of codemods that will automatically transform the deprecated "object" syntax into the equivalent "builder" syntax.
+
+The codemods package is available on NPM as [**`@reduxjs/rtk-codemods`**](https://www.npmjs.com/package/@reduxjs/rtk-codemods). It currently contains two codemods: `createReducerBuilder` and `createSliceBuilder`.
+
+To run the codemods against your codebase, run `npx @reduxjs/rtk-codemods <TRANSFORM NAME> path/of/files/ or/some**/*glob.js`.
+
+Examples:
+
+```bash
+npx @reduxjs/rtk-codemods createReducerBuilder ./src
+
+npx @reduxjs/rtk-codemods createSliceBuilder ./packages/my-app/**/*.ts
+```
+
+We also recommend re-running Prettier on the codebase before committing the changes.
+
+**These codemods _should_ work, but we would greatly appreciate testing and feedback on more real-world codebases!**
+
+Before:
+
+```js
+createReducer(initialState, {
+  [todoAdded1a]: (state, action) => {
+    // stuff
+  },
+  [todoAdded1b]: (state, action) => action.payload,
+})
+
+const slice1 = createSlice({
+  name: 'a',
+  initialState: {},
+  extraReducers: {
+    [todoAdded1a]: (state, action) => {
+      // stuff
+    },
+    [todoAdded1b]: (state, action) => action.payload,
+  },
+})
+```
+
+After:
+
+```js
+createReducer(initialState, (builder) => {
+  builder.addCase(todoAdded1a, (state, action) => {
+    // stuff
+  })
+
+  builder.addCase(todoAdded1b, (state, action) => action.payload)
+})
+
+const slice1 = createSlice({
+  name: 'a',
+  initialState: {},
+
+  extraReducers: (builder) => {
+    builder.addCase(todoAdded1a, (state, action) => {
+      // stuff
+    })
+
+    builder.addCase(todoAdded1b, (state, action) => action.payload)
+  },
+})
+```

.yarnrc.yml

@@ -3,7 +3,7 @@
   "devDependencies": {
     "@manaflair/redux-batch": "^1.0.0",
     "@types/nanoid": "^2.1.0",
-    "@types/react": "^16.9.46",
+    "@types/react": "^18.0",
     "@types/redux-logger": "^3.0.8",
     "async-mutex": "^0.3.2",
     "axios": "^0.20.0",

docs/api/codemods.mdx

@@ -380,6 +380,15 @@ If you specify `track: false` when manually dispatching queries, RTK Query will
 
 _(required if no `queryFn` provided)_
 
+```ts title="query signature" no-transpile
+export type query = <QueryArg>(
+  arg: QueryArg
+) => string | Record<string, unknown>
+
+// with `fetchBaseQuery`
+export type query = <QueryArg>(arg: QueryArg) => string | FetchArgs
+```
+
 [summary](docblock://query/endpointDefinitions.ts?token=EndpointDefinitionWithQuery.query)
 
 [examples](docblock://query/endpointDefinitions.ts?token=EndpointDefinitionWithQuery.query)
@@ -490,12 +499,45 @@ See also [Invalidating cache data](../usage/automated-refetching.mdx#invalidatin
 
 _(optional, only for query endpoints)_
 
-Overrides the api-wide definition of `keepUnusedDataFor` for this endpoint only.
+Overrides the api-wide definition of `keepUnusedDataFor` for this endpoint only.a
 
 [summary](docblock://query/createApi.ts?token=CreateApiOptions.keepUnusedDataFor)
 
 [examples](docblock://query/createApi.ts?token=CreateApiOptions.keepUnusedDataFor)
 
+### `serializeQueryArgs`
+
+_(optional, only for query endpoints)_
+
+[summary](docblock://query/endpointDefinitions.ts?token=QueryExtraOptions.serializeQueryArgs)
+
+[examples](docblock://query/endpointDefinitions.ts?token=QueryExtraOptions.serializeQueryArgs)
+
+### `merge`
+
+_(optional, only for query endpoints)_
+
+[summary](docblock://query/endpointDefinitions.ts?token=QueryExtraOptions.merge)
+
+[examples](docblock://query/endpointDefinitions.ts?token=QueryExtraOptions.merge)
+
+### `forceRefetch`
+
+_(optional, only for query endpoints)_
+
+```ts title="forceRefetch signature" no-transpile
+type forceRefetch = (params: {
+  currentArg: QueryArg | undefined
+  previousArg: QueryArg | undefined
+  state: RootState<any, any, string>
+  endpointState?: QuerySubState<any>
+}) => boolean
+```
+
+[summary](docblock://query/endpointDefinitions.ts?token=QueryExtraOptions.forceRefetch)
+
+[examples](docblock://query/endpointDefinitions.ts?token=QueryExtraOptions.forceRefetch)
+
 ### `onQueryStarted`
 
 _(optional)_

docs/package.json

@@ -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.