v2.0.0-alpha.0

This is the initial alpha release for Redux Toolkit 2.0. This release has breaking changes.

Please try this out and let us know of any build or runtime incompatibilities beyond the expected breaking changes!

See the RTK 2.0 planning issue for discussion of likely upcoming changes.

Changelog

Removal of Object Object Argument for createReducer and createSlice.extraReducers

As described in the RTK v1.9.0 release notes, we've removed the object form for createReducer and createSlice.extraReducers. Use the "builder callback" form instead.

See the 1.9 release notes for examples of what the necessary changes look like, and details on the available codemod for automatically making this change to your source.

Modernized Build Output Formats

This release drops backwards-compatibility aspects for IE11 in our published package build artifacts:

All module formats (CJS and ESM) now contain code that targets the latest ES spec and no longer backwards-compiled to ES5 syntax

Later 2.0-alpha releases will add full Node ESM support with exports in package.json, and may contain other build artifact changes as well.

Build Tooling Updates

We've updated our own build process to use the latest ESBuild and TS versions.

v1.9.1

This bugfix release fixes assorted issues that were reported with RTK 1.9.0, and adds a few additional requested tweaks and improvements.

Changelog

Fixes

The createAsyncThunk.withTypes function was fully broken (it type-checked correctly, but pointed to the wrong function due to a name shadowing issue). That now works correctly.

The maxRetries option for RTKQ was inadvertently filtering out 0 values, and those are now accepted.

fulfillWithValue had incorrect types that made it appear as if the data was nested an additional level deeper. The types are now correct.

The ActionCreatorWithoutPayload type was tweaked to force an error when an action creator is accidentally called with an argument, which happens in cases like onClick={todoAdded}. This avoids accidentally passing values like React event objects as the payload.

Timer handling for batchActions and autoBatchEnhancer now works in more JS runtime environments.

Other Changes

The TagDescription type is now exported from RTKQ.

API endpoints now have a .name field containing the endpoint name, such as "getPokemon".

Calling promise.abort() on a createAsyncThunk promise before an async condition resolves will now be treated as if the condition itself returned false, bailing out and not dispatching anything.

The merge option now receives a third argument containing {arg, baseQueryMeta, fulfilledTimeStamp, requestId}, in case that info is useful in deciding how to merge.

The @reduxjs/rtk-codemods package has been updated to fix cases where the createSliceBuilder codemod didn't preserve fields with function variable arguments, like [todoAdded]: adapter.addOne. That package has been updated to v0.0.3.

What's Changed

• fix createAsyncThunk.withTypes by @phryneas in #2885
• Update timer polyfills to work in more environments by @markerikson in #2887
• Retry now checks whether potential retry counts are undefined, rather than boolean, in order to avoid filtering out 0's by @OliverRadini in #2958
• Fix multiple small issues with 1.9 by @markerikson in #2964
• fulfillWithValue should infer return value by @phryneas in #2888
• Fix Identifier/MemberExpression values in createSliceBuilder codemod by @kyletsang in #2881
• Additional 1.9.1 fixes by @markerikson in #2965

Full Changelog: v1.9.0...v1.9.1

v1.9.0

This feature release adds several new options for RTK Query's createApi and fetchBaseQuery APIs, adds a new upsertQueryData util, rewrites RTKQ's internals for improved performance, adds a new autoBatchEnhancer, deprecates the "object" syntax for createReducer and createSlice.extraReducers, deprecates and removes broken utils for getting running query promises, improves TS inference, exports additional types, and fixes a number of reported issues.

npm i @reduxjs/toolkit@latest

yarn add @reduxjs/toolkit@latest

We plan to start work on RTK 2.0 in the next few weeks. RTK 2.0 will focus on dropping legacy build compatibility and deprecated APIs, with some potential new features. See the linked discussion thread and give us feedback on ideas!

Deprecations and Removals

Object Argument for createReducer and createSlice.extraReducers

RTK's createReducer API was originally designed to accept a lookup table of action type strings to case reducers, like { "ADD_TODO" : (state, action) => {} }. We later added the "builder callback" form to allow more flexibility in adding "matchers" and a default handler, and did the same for createSlice.extraReducers.

We intend to remove the "object" form for both createReducer and createSlice.extraReducers in RTK 2.0. The builder callback form is effectively the same number of lines of code, and works much better with TypeScript.

Starting with this release, RTK will print a one-time runtime warning for both createReducer and createSlice.extraReducers if you pass in an object argument.

As an example, this:

const todoAdded = createAction('todos/todoAdded');

createReducer(initialState, {
  [todoAdded]: (state, action) => {}
})

createSlice({
  name,
  initialState,
  reducers: {/* case reducers here */},
  extraReducers: {
    [todoAdded]: (state, action) => {}
  }
})

should be migrated to:

createReducer(initialState, builder => {
  builder.addCase(todoAdded, (state, action) => {})
})

createSlice({
  name,
  initialState,
  reducers: {/* case reducers here */},
  extraReducers: builder => {
    builder.addCase(todoAdded, (state, action) => {})
  }
})

Codemods for Deprecated Object Reducer Syntax

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

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!

Object reducer codemod before/after examples

Before:

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:

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);
  }
})

getRunningOperationPromises Deprecation and Replacement

In v1.7.0, we added an api.util.getRunningOperationPromises() method for use with SSR scenarios, as well as a singular getRunningOperationPromise() method intended for possible use with React Suspense.

Unfortunately, in #2477 we realized that both those methods have a fatal flaw - they do not work with multiple stores in SSR.

As of this release, we are immediately marking getRunningOperationPromises() as deprecated and discouraging its use before we remove it completely in RTK 2.0! It will now throw both runtime and compile errors in development to enforce moving away from using it. However, we are leaving its existing behavior in production builds to avoid actual breakage.

The getRunningOperationPromise() util was experimental, and as far as we can tell not actually being used by anyone, so we are removing getRunningOperationPromise completely in this release.

As replacements, RTKQ now includes four new thunks attached to api.util:

• getRunningQueryThunk(endpointName, queryArgs)
• getRunningMutationThunk(endpointName, fixedCacheKeyOrRequestId)
• getRunningQueriesThunk()
• getRunningMutationsThunk()

Usages would typically change like this:

-await Promise.all(api.util.getRunningOperationPromises())
+await Promise.all(dispatch(api.util.getRunningQueriesThunk()))

Changelog

New RTK Query createApi Options

createApi endpoints now have several additional options that can be passed in, some of which are intended to work together.

merge Option

RTKQ was built around the assumption that the server is the source of truth, and every refetch replaces the cached data on the client. There are use cases when it would be useful to merge an incoming response into the existing cached data instead, such as pagination or APIs that return varying results over time.

Query endpoints can now accept a merge(cachedData, responseData) callback that lets you do Immer-powered "mutations" to update the existing cached data instead of replacing it entirely.

Since RTKQ assumes that each response per key should replace the existing cache entry by default, the merge option is expected to be used with the serializeQueryArgs and forceRefetch options, as described below.

serializeQueryArgs Option

RTK Query always serializes the cache key value, and uses the string as the actual key for storing the cache entry. The default serialization is the name of the endpoint, plus either the primitive value or a stable-serialized object. An example might be state.api.queries['getPokemon("pikachu")'].

RTKQ already supported customization of this serialization behavior at the createApi level. Now, each endpoint can specify its own serializeQueryArgs method.

The per-endpoint serializeQueryArgs may return either a string, an object, a number, or a boolean. If it's a string, that value will be used as-is. Otherwise, the return value will be run through the default serialization logic. This simplifies the common case of stripping out a couple unwanted object fields from the cache key.

This option serves two main purposes: leaving out values that are passed in to an endpoint but not really part of the "key" conceptually (like a socket or client instance), and altering cache key behavior to use a single entry for the endpoint (such as in an infinite loading / pagination scenario).

Also, the defaultSerializeQueryArgs util is now exported.

    getPost: build.query<Post, { id: string; client: MyApiClient }>({
      queryFn: async ({ id, client }) => {
        const post = await client.fetchPost(id)
        return { data: post }
      },
      serializeQueryArgs: ({ queryArgs, endpointDefinition, endpointName }) => {
        const { id } = queryArgs
        // This can return a string, an object, a number, or a boolean.
        // If it returns an object, number or boolean, that value
        // will be serialized automatically via `defaultSerializeQueryArgs`
        return { id } // omit `client` from the cache key

        // Alternately, you can use `defaultSerializeQueryArgs`:
        // return defaultSerializeQueryArgs({
        //   endpointName,
        //   queryArgs: { id },
        //   endpointDefinition
        // })
        // Or  create and return a string yourself:
        // return `getPost(${id})`
      },
    }),

forceRefresh option

Sometimes you may want to force a refetch, even though RTKQ thinks that the serialized query args haven't changed and there's already a fulfilled cache entry.

This can be used to force RTKQ to actually refetch. One expected use case is an "infinite pagination" scenario where there is one cache entry for the endpoint, different page numbers are given as query args, and the incoming responses are merged into the existing cache entry:

    listItems: build.query<string[], number>({
      query: (pageNumber) => `/listItems?page=${pageNumber}`,
      // Only have one cache entry because the arg always maps to one string
      serializeQueryArgs: ({ endpointName }) => {
        return endpointName
      },
      // Always merge incoming data to the cache entry
      merge: (currentCache, newItems) => {
        currentCache.push(...newItems)
      },
      // Refetch when the page arg changes
      forceRefetch({ currentArg, previousArg }) {
        return currentArg !== previousArg
      },
    }),

transformErrorResponse Option

Similar to transformResponse, endpoints ...

v1.9.0-rc.1

This release candidate updates the auto-batching enhancer to accept additional options for queuing subscriber notifications, and improves RTKQ perf by removing some unnecessary internal memoized selectors.

Please try this out and give us feedback (even if it's just "tried updating and everything's fine")! If no further issues come up we intend to publish 1.9 in the next few days.

npm i @reduxjs/toolkit@next

yarn add @reduxjs/toolkit@next

Docs updates for 1.9 are complete, and can be viewed here:

https://deploy-preview-2401--redux-starter-kit-docs.netlify.app/

Changelog

Autobatch Enhancer Options

The initial implementation of the autoBatchEnhancer() always queued delayed subscriber notifications using queueMicrotask. We've updated it to accept alternate options that queue with setTimeout, requestAnimationFrame, or bring-your-own-callback (more similar to redux-batched-subscribe).

The variation in JS event loop timing behavior (microtasks, macrotasks, and frames) means having these options may be useful in different situations.

What's Changed

• Fix "running thunks" types and remove unnecessary RTKQ selectors by @markerikson in #2856
• Make autobatching notification queueing configurable by @markerikson in #2857

Full Changelog: v1.9.0-rc.0...v1.9.0-rc.1

v1.9.0-rc.0

This release candidate includes a new "auto-batching" store enhancer, support for passing some global options to fetchBaseQuery, a fix for forceRefetch behavior, and internal tweaks to checks for missing RTKQ middleware setup.

Please try this out and give us feedback (even if it's just "tried updating and everything's fine")! If no further issues come up we intend to publish 1.9 in the next few days.

npm i @reduxjs/toolkit@next

yarn add @reduxjs/toolkit@next

Docs updates for 1.9 are complete, and can be viewed here:

https://deploy-preview-2401--redux-starter-kit-docs.netlify.app/

Changelog

New Auto-Batching Store Enhancer

There are several different ways to "batch actions" with Redux stores, ranging from reducers to debounced subscriber notifications.

RTK now includes a new autoBatchEnhancer() store enhancer that uses a variation on the "debounced notification" approach, inspired by React's technique of batching renders and determining if an update is low-priority or high-priority.

The enhancer looks for any actions tagged with an action.meta[SHOULD_AUTOBATCH] = true flag, and delays notifying subscribers until the end of the event loop tick. This means that if multiple "auto-batched" actions are dispatched in a row, there will be only one subscriber notification. However, if any "normal-priority" action without that flag is dispatched in the same tick, the enhancer will notify subscribers immediately.

This allows Redux users to selectively tag certain actions for effective batching behavior, making this purely opt-in on a per-action basis, while retaining normal notification behavior for all other actions.

RTK Query's internals have been updated to mark several key actions as batchable. While the enhancer is purely opt-in, benchmarks indicate that it can help speed up UI performance with RTK Query, especially when rendering many components with query hooks. We recommend adding it to your store setup:

  const store = configureStore({
  reducer,
  enhancers: (existingEnhancers) => {
    // Add the autobatch enhancer to the store setup
    return existingEnhancers.concat(autoBatchEnhancer())
  },
})

Additionally, there's a prepareAutoBatched util that can be used to help add the SHOULD_AUTOBATCH flag to actions, designed for use with createSlice:

const counterSlice = createSlice({
  name: 'counter',
  initialState: { value: 0 } as CounterState,
  reducers: {
    incrementBatched: {
      // Batched, low-priority
      reducer(state) {
        state.value += 1
      },
      // Use the `prepareAutoBatched` utility to automatically
      // add the `action.meta[SHOULD_AUTOBATCH]` field the enhancer needs
      prepare: prepareAutoBatched<void>(),
    },
    // Not batched, normal priority
    decrementUnbatched(state) {
      state.value -= 1
    },
  },
})

fetchBaseQuery Global Options

fetchBaseQuery now supports passing the responseHandler, validateStatus, and timeout options directly to fetchBaseQuery itself, in addition to accepting it as part of specific endpoints. If provided, these options will be applied as defaults to all requests for that API, which simplifies using them on many endpoints.

Other Changes

Providing serializeQueryArgs and forceRefetch options for an endpoint now works correctly when you pass an object as the cache key argument to a query hook.

The defaultSerializeQueryArgs util is now exported.

The endpoint-specific serializeQueryArgs option now allows returning an object or a number instead of just a string. If a string is returned, it will be used as-is for the serialized cache key. If an object or number is returned, that value will be passed to defaultSerializeQueryArgs. This simplifies the common case of wanting to remove a couple fields from the cache key, without needing to call defaultSerializeQueryArgs yourself.

Internal tweaks to the RTKQ middleware behavior for detecting cases where the middleware has not been added to the store.

The API docs for the 1.9 preview are fully updated.

What's Changed

• Fill out v1.9 remaining docs by @markerikson in #2804
• Rework endpoint serializeQueryArgs to allow object/number returns by @markerikson in #2835
• allow for global responseHandler and validateStatus configuration by @phryneas in #2823
• Fix refetches when sQA returns same value and queryArgs are object by @markerikson in #2844
• Add an auto-batching enhancer that delays low-pri notifications and use with RTKQ by @markerikson in #2846
• Check middleware registration directly to avoid persistence issues by @markerikson in #2850

Full Changelog: v1.9.0-beta.0...v1.9.0-rc.0

v1.9.0-beta.0

This feature-complete preview release includes several new options for RTK Query API endpoints as well as the ability to "upsert" data, performance improvements to the RTK Query middleware, improvements to fetchBaseQuery behavior, several TS types tweaks and additional type exports, a runtime deprecation warning for the object argument form of createReducer and createSlice.extraReducers, and codemods to update those methods.

Please try this out and give us feedback (even if it's just "tried updating and everything's fine")! We believe that all changes intended for 1.9 are stable and should work, but as always we'd appreciate real-world checks to confirm that.

npm i @reduxjs/toolkit@next

yarn add @reduxjs/toolkit@next

Docs updates for 1.9 are in progress and can be viewed here:

https://deploy-preview-2401--redux-starter-kit-docs.netlify.app/

Changes Since Alpha

Codemods for Deprecated Object Reducer Syntax

Per the description in 1.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. 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:

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:

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:

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);
  }
})

getRunningOperationPromises Deprecation and Replacement

In v1.7.0, we added an api.util.getRunningOperationPromises() method for use with SSR scenarios, as well as a singular getRunningOperationPromise() method intended for possible use with React Suspense.

Unfortunately, in #2477 we realized that both those methods have a fatal flaw - they do not work with multiple stores in SSR.

As of this release, we are immediately marking getRunningOperationPromises() as deprecated and discouraging its use before we remove it completely in RTK 2.0! It will now throw both runtime and compile errors in development to enforce moving away from using it. However, we are leaving its existing behavior in production builds to avoid actual breakage.

The getRunningOperationPromise() util was experimental, and as far as we can tell not actually being used by anyone, so we are removing getRunningOperationPromise completely in this release.

As replacements, RTKQ now includes four new thunks attached to api.util:

• getRunningQueryThunk(endpointName, queryArgs)
• getRunningMutationThunk(endpointName, fixedCacheKeyOrRequestId)
• getRunningQueriesThunk()
• getRunningMutationsThunk()

Usages would typically change like this:

-await Promise.all(api.util.getRunningOperationPromises())
+await Promise.all(dispatch(api.util.getRunningQueriesThunk()))

Summary of Alpha Changes

See the previous release notes for more details.

RTK Query Options

• API endpoints:
  • serializeQueryArgs option ( #2493 )
  • merge option ( #1059 )
  • forceRefetch option ( #2663 )
  • transformErrorResponse option ( #1841
• upsertQueryData util ( #2266 )
• RTKQ middleware optimization ( #2641, #2759 )
• fetchBaseQuery options:
  • jsonContentType ( #2403 )
  • timeout ( #2363 )
  • content-type response handler ( #2363 )
  • prepareHeaders can return void ( #2775 )
• hook triggers return promises ( #2212 )
• retry conditions by response ( #2239 )

TS Types

• action types are now template literals ( #2250 )
• Store enhancer types ( #2550 )
• createAsyncThunk.withTypes ( #2604 )
• Several additional exported types:
  • #2276
  • #1646
  • #2740

TS Support Matrix

Redux Toolkit now requires TypeScript 4.2 or higher, and works correctly with TS 4.8.

v1.9.0-alpha.2

This feature preview release fixes broken behavior in the new upsertQueryData API, fixes behavior with the serializeQueryArgs+merge combination by adding a new forceRefetch option, rewrites the internal subscription tracking to speed up mount/update times, adds new TS type exports, and includes the bug fixes from 1.8.6.

Changelog

upsertQueryData Fix

We released the new upsertQueryData util in 1.9.0-alpha.1, but the behavior didn't actually work as intended in some cases. We've tweaked the implementation and it now should work correctly. Please try it out and let us know!

New forceRefresh option and Infinite Loading Usages

In earlier alphas, we added a new serializeQueryArgs endpoint option to allow customization of cache keys. This serves two purposes: leaving out values that are passed in to an endpoint but not really part of the "key" conceptually (like a socket or client instance), and altering cache key behavior to use a single entry for the endpoint such as in an infinite loading / pagination scenario.

Along with that, we also added a merge option that lets you modify the contents of an existing cache entry when new data is received, instead always replacing it.

Due to the existing internal logic, these two options are insufficient for the infinite loading / pagination case. For example, changing useGetItemsQuery(pageNum) from 1 to 2 starts the checks for fetching new data, but it bails out internally because there's already a cache entry that is status: fulfilled for that endpoint and cache key.

We've added an additional forceRefresh call back that receives {currentArg, previousArg, state, endpointState} as arguments. Use this in combination with the other options to force this endpoint to refetch when args change despite a single cache entry already existing, such as this example:

forceRefetch({currentArg, previousArg}) {
  // Assume these are page numbers
  return currentArg !== previousArg
},
serializeQueryArgs({endpointName}) {
  // Will only have one cache entry for this endpoint, because of the consistent name
  return endpointName
},
merge(currentCacheData, responseData) {
  // Always add incoming data to the existing cache entry
  currentCacheData.push(...responseData)
}

The forceRefresh option may also be useful in other app-specific scenarios as well.

Internal Subscription Logic Rewrite

RTKQ tracks subscription entries, and thus far has done so by saving them in the Redux state and updating that by dispatching actions as each query hook loads. We've seen that this can be a performance bottleneck in edge cases where hundreds of query hooks are being mounted at once. (This shouldn't be a concern in most apps, but some users were stress-testing things :) )

We've reworked the internal RTKQ middleware logic to track most of the subscription data inside the middleware and sync it to the Redux store at the end of an event loop tick. This should speed up those large list edge cases by cutting 90% of the startup time.

What's Changed

• fix upsertQueryData race situations by @phryneas in #2646
• Fix upsert by @phryneas in #2669
• Export the BaseQueryApi interface from rtk-query so it can be used as a type in TypeScript without importing from dist/. by @nsthorat in #2740
• Fix retryCondition error. by @phryneas in #2743
• fix: export ToolkitStore interface from configureStore by @adamhari in #2750
• Fix the dispatch type inference to correctly handle read-only middleware arrays by @dokmic in #2629
• fix(toolkit): export "ThunkMiddleware" from redux-thunk by @VinceOPS in #2745
• Remove previous api tags before adding new provided tags by @Bezmehrabi in #2702
• reset dispatchQueued variable after flushing by @phryneas in #2757
• Fix invalidateTags by @manceau-jb in #2721
• Add forceRefetch to QueryExtraOptions by @schadenn in #2663
• Speed up subscription behavior by tracking state in middleware by @markerikson in #2759

Full Changelog: v1.9.0-alpha.1...v1.9.0-alpha.2

v1.8.6

This bugfix release fixes a couple of issues with RTKQ endpoint tags not invalidating correctly, and tweaks the dispatch type inference to handle more variations of arrays.

What's Changed

• Fix the dispatch type inference to correctly handle read-only middleware arrays by @dokmic in #2629
• fix(toolkit): export "ThunkMiddleware" from redux-thunk by @VinceOPS in #2745
• Remove previous api tags before adding new provided tags by @Bezmehrabi in #2702
• Fix invalidateTags by @manceau-jb in #2721

Full Changelog: v1.8.5...v1.8.6

v1.9.0-alpha.1

This feature preview release adds new options and improves behavior for RTK Query.

As of this alpha, RTK 1.9 is feature-complete and we do not expect additional meaningful changes. The remaining work is filling out docs and preparing the "object reducer" codemods for release alongside 1.9.

Still no specific ETA for release, but we hope for Soon (TM) :)

Changelog

upsertQueryData API

RTKQ already has an updateQueryData util to synchronously modify the contents of an existing cache entry, but there was no way to create a new cache entry and its metadata programmatically.

This release adds a new api.util.upsertQueryData API that allows creating a cache entry + its data programmatically. As with the other util methods, this is a thunk that should be dispatched, and you should pass in the exact cache key arg and complete data value you want to insert:

dispatch(
  api.util.upsertQueryData('post', '3', {
    id: '3',
    title: 'All about cheese.',
    contents: 'I love cheese!',
   })
)

RTKQ Middleware Performance Optimizations

RTKQ automatically generates a Redux middleware for each "API slice" / createApi call. That middleware itself has been made up of 7 individual middleware internally composed into the final middleware, with each individual middleware responsible for a different task like managing polling or cache lifetimes.

While this worked well for encapsulating responsibilities, it also meant that every dispatched Redux action had to go through 7 additional middleware. This added multiple function calls to each dispatch's stack trace, and even if there isn't a noticeable perf hit, it wasn't efficient. We've also had some reports that users with multiple API slices were occasionally seeing "Maximum call stack size exceeded" errors.

We've rewritten the internals of the middleware to be more efficient. Actions now only receive extra processing if they're actually related to the API slice itself, and that processing is done via a loop over handling logic at the end of the middleware unwind phase, rather than nesting function calls through multiple sub-middleware. That should keep the call stack shorter in the cases where API actions really are being processed.

Other RTKQ Updates

The refetch() methods now return a promise that can be awaited.

Query endpoints can now accept a retryCondition callback as an alternative to maxRetries. If you provide retryCondition, it will be called to determine if RTKQ should retry a failed request again.

What's Changed

• return promise from query result & hook refetch by @phryneas in #2212
• retry condition by http error response by @kahirokunn in #2239
• implemented upsertQueryData functionality per #1720 #2007 by @barnabasJ in #2266
• Consolidate RTKQ middleware to simplify stack size by @markerikson in #2641
• Add TS 4.8 to the test matrix by @markerikson in #2642
• Try fixing createAsyncThunk issues with TS 4.8 by @markerikson in #2643
• Fix assorted issues with the RTKQ middleware refactor by @markerikson in #2644

Full Changelog: v1.9.0-alpha.0...v1.9.0-alpha.1

v1.9.0-alpha.0

This feature preview release adds new options and improves behavior for RTK Query, adds a runtime deprecation for the "object" form of createReducer/createSlice.extraReducers, adds the ability to define a "pre-typed" version of createAsyncThunk, improves TS inference of store enhancers, and exports additional TS types.

We hope to add a couple additional RTKQ options as part of the final 1.9 release, including an upsertQueryData util. See the RTK 1.9 milestone for remaining items. No hard ETA yet, but ideally we'd like to publish 1.9 within the next couple weeks if we can wrap things up.

Notable Changes

Some highlights for this alpha:

RTKQ merge Option

RTKQ was built around the assumption that the server is the source of truth, and every refetch replaces the cached data on the client. There are use cases when it would be useful to merge an incoming response into the existing cached data instead, such as pagination or APIs that return varying results over time.

Query endpoints can now accept a merge(cachedData, responseData) callback that lets you do Immer-powered "mutations" to update the existing cached data instead of replacing it entirely.

Object Reducer Deprecation Warning

RTK's createReducer API was originally designed to accept a lookup table of action type strings to case reducers, like { "ADD_TODO" : (state, action) => {} }. We later added the "builder callback" form to allow more flexibility in adding "matchers" and a default handler, and did the same for createSlice.extraReducers.

We intend to remove the "object" form for both createReducer and createSlice.extraReducers in RTK 2.0. The builder callback form is effectively the same number of lines of code, and works much better with TypeScript.

Starting with this release, RTK will print a one-time runtime warning for both createReducer and createSlice.extraReducers if you pass in an object argument.

As an example, this:

const todoAdded = createAction('todos/todoAdded');

createReducer(initialState, {
  [todoAdded]: (state, action) => {}
})

createSlice({
  name,
  initialState,
  reducers: {/* case reducers here */},
  extraReducers: {
    [todoAdded]: (state, action) => {}
  }
})

should be migrated to:

createReducer(initialState, builder => {
  builder.addCase(todoAdded, (state, action) => {})
})

createSlice({
  name,
  initialState,
  reducers: {/* case reducers here */},
  extraReducers: builder => {
    builder.addCase(todoAdded, (state, action) => {})
  }
})

We have initial codemods in the repo that will help rewrite the object form to the builder form, and we'll publish those with instructions alongside 1.9 when it goes final.

RTKQ Internal Improvements

When query hooks mount, they dispatch actions to subscribe to the relevant data. The first hook to do so will dispatch a "subscription/fulfilled" action, and all further hooks asking for the same cache key will dispatch "subscription/rejected" actions. Both cause the reducer logic to add another entry to the subscription tracking.

The dispatching of individual "subscription/rejected" actions was causing perf issues when many components mounted at once, due to the number of extra dispatches. RTKQ now batches those into a single combined action per event loop tick, which improves perf for some many-component use cases noticeably.

TS Types

configureStore now correctly infers changes to the store shape from any store enhancers.

There's now a createAsyncThunk.withTypes() method that can be used to create a "pre-typed" version of createAsyncThunk with types like {state, dispatch, extra} baked in.

What's Changed

• Add isJsonContentType predicate to fetchBaseQuery by @msutkowski in #2331
• Add jsonContentType to fetchBaseQuery options by @msutkowski in #2403
• Add ThunkMiddleware to the re-exported types from redux-thunk by @orta in #2451
• add timeout option to fetchBaseQuery by @phryneas in #2143
• createSlice: use template literal types for action type by @phryneas in #2250
• add types for manually typing hook results in userland code by @phryneas in #2276
• Add 'content-type' ResponseHandler by @taylorkline in #2363
• feature : endpoint-specific args serializers by @michal-kurz in #2493
• RFC: add "merge" functionality by @phryneas in #1059
• Add runtime deprecation warning for reducer object notation by @markerikson in #2591
• feat: Add the ability to type StoreEnhancers by @fostyfost in #2550
• Batch RTKQ "subscribe on reject" actions, and improve cache collection timer handling by @markerikson in #2599
• add transformErrorReponse to rtkq endpoints by @dreyks in #1841
• Fix manually initiate()d rtk-query promises by @wesen in #2187
• Implement codemods for createReducer and createSlice builder by @markerikson in #2602
• RFC: Expose endpoint types by @phryneas in #1646
• add createAsyncThunk.withTypes by @phryneas in #2604

Full Changelog: v1.8.5...v1.9.0-alpha.0