v2.14.0

[markerikson]

This feature release speeds up the dispatch path and RTK Query's Api type checking, shrinks createSlice in esbuild bundles, adds RTK-owned Draft and Patch types so emitted declarations no longer reference Immer, adds removeMany({ where }) and selectByIds to the entity adapter, adds RTK Query cache entry selectors and a DevTools action sanitizer, and fixes a very long list of RTK Query lifecycle, polling, upsert, timer, hook and fetchBaseQuery bugs.

Note that we just announced our roadmap to Redux Toolkit 3.0, which includes both a large set of planned 2.x features and improvements, and planned 3.0 breaking changes. The fixes and updates in this release help pave the way for all of those efforts. We'd also appreciate feedback on the linked RTK Query usage patterns and 3.0 planned breaking changes discussion threads.

Changelog

Dispatch Performance

Every dispatched action runs through every reducer and middleware, so small costs on that path add up. We added a benchmark harness for the dispatch path and used it to find several places where RTK did work for actions it didn't care about.

createAction(...).match now compares action.type before calling isAction, so a non-matching action costs a property read. createReducer no longer allocates arrays on every dispatch to collect case and matcher reducers. Since createSlice builds its reducer with createReducer, every slice reducer gets this improvement.

The listener middleware used to copy its listener list and call every predicate for every action. It now keeps a snapshot that is rebuilt only when listeners are added or removed, and that snapshot knows which action types have type or actionCreator listeners. If an action's type isn't in that set and there are no matcher or predicate listeners, the middleware skips the loop entirely.

The RTK Query root reducer now returns the existing state for actions that none of its slices handle, instead of running all five slice reducers. It also skips rewriting a query's provided tags when the new tags are the same as the stored ones, so re-fetching a query that returns the same tags no longer creates new provided state.

Some numbers from the PR benchmarks (Node 26, ops/sec unless noted):

Scenario	Before	After
Listener middleware, 200 listeners, unrelated action	108K	5.34M
Listener middleware, 200 actionCreator listeners, matching action	100K	612K
createSlice, 20 slices, unrelated action	320K	394K
RTKQ store, unrelated action	352K	468K
RTKQ re-dispatch of a fulfilled query with unchanged tags, 1000 entries (ms per dispatch)	2.50	0.55

The listener middleware numbers are the biggest change, because the old cost grew with the number of listeners. Apps with a handful of listeners will see much smaller gains.

The RTK Query middleware also does less work keeping the store's subscriptions state in sync (#5499). It used to JSON-copy the whole subscriptions object and diff it with Immer every 500ms while subscriptions were changing. It now records which cache keys changed and writes one patch per key. Keys that didn't change keep their object references, so the Redux DevTools no longer receive a full copy of subscriptions on every sync. Polls, refetch() calls and tag invalidation refetches don't add subscribers, so they no longer schedule a sync at all. The visible difference: a cache key that only ever had subscribe: false requests no longer shows up as an empty {} in subscriptions.

Smaller createSlice Bundles With esbuild

createSlice references asyncThunkCreator so that create.asyncThunk works in the reducers callback. esbuild couldn't tell that the asyncThunkCreator object was free of side effects, so it always bundled createAsyncThunk along with createSlice. webpack already dropped it. We've marked it as pure, and an esbuild bundle that imports only createSlice is now about 1 kB smaller (brotli).

Faster RTK Query Api Type Checking

The Api type combines every registered module (core, React hooks, and any third-party modules) by running UnionToIntersection over the module names. TanStack Table hit the same cost with the same design, and found that writing out the known intersection and adding variance annotations helped a lot.

We've done the same thing here: Api uses the core module type directly, and ApiModules has in out variance annotations. On a test app with one ~50-endpoint createApi, type instantiations dropped 22% and check time dropped about 25% on TS 6, and about 18% on the TS 7 native preview. Third-party modules like ngrx-rtk-query saw 7-8% fewer instantiations. There are no runtime changes.

RTK-Owned Draft and Patch Types

RTK used to re-export Immer's Draft type, and used Immer's types in signatures like CaseReducer and PatchCollection. That meant the .d.ts files TypeScript generated for your slices referenced immer. With a package manager layout where immer isn't hoisted, those declarations failed to build with TS2883 (#5516). Re-exporting doesn't fix that, so RTK now declares its own Draft, WritableDraft and Patch types with the same shapes as Immer's. Emitted declarations now point at @reduxjs/toolkit instead. Our type tests check that RTK's Draft and Immer's Draft stay interchangeable, so code that mixes castDraft or current with RTK's types keeps working. We also bumped the immer dependency to ^11.2.9.

There are a few other type additions in this release:

• ApiRootState replaces RTK Query's RootState type, which is now deprecated. RootState will be removed in 3.0.
• TypedAddListenerAction and TypedRemoveListenerAction describe the actions that addListener and removeListener actually dispatch. The default payload type of TypedAddListener and TypedRemoveListener is now the listener options object, so addListener.match(action) no longer claims action.payload has fields like id and unsubscribe that don't exist at runtime.
• dispatch(removeListener(...)) is typed as returning boolean and dispatch(clearAllListeners()) as returning void, matching the runtime.
• UseQueryStateDefaultResult and UseInfiniteQueryStateDefaultResult are exported from @reduxjs/toolkit/query/react, for wrapping hooks with a generic selectFromResult.

RTK Query Cache Entry Selectors

We've had requests for a way to list everything in the cache for an endpoint (#2995). api.util.selectEntriesForEndpoint(state, endpointName) returns all cache entries for one query or infinite query endpoint, and api.util.selectAllQueryEntries(state) returns them for every endpoint. Each item has the entry's fields plus its queryCacheKey, and is typed for its endpoint. Both selectors are memoized. There's also a new exported QueryCacheEntry<Definition> type.

const postEntries = api.util.selectEntriesForEndpoint(state, 'getPost')
const loadedPostIds = postEntries
  .filter((entry) => entry.status === 'fulfilled')
  .map((entry) => entry.originalArgs)

DevTools Action Sanitizer

All RTK Query requests use the same few action types, so the Redux DevTools show a long list of api/executeQuery/fulfilled actions, and you have to open each one to see which endpoint it was for. The new createApiActionSanitizer(api) returns a function for the DevTools actionSanitizer option that renames those actions for display, like api/executeQuery/fulfilled (getPosts). The dispatched actions aren't modified.

import { configureStore } from '@reduxjs/toolkit'
import { createApiActionSanitizer } from '@reduxjs/toolkit/query'
import { api } from './api'

export const store = configureStore({
  reducer: {
    [api.reducerPath]: api.reducer,
  },
  middleware: (getDefaultMiddleware) =>
    getDefaultMiddleware().concat(api.middleware),
  devTools: {
    actionSanitizer: createApiActionSanitizer(api),
  },
})

See the createApiActionSanitizer docs for combining sanitizers for multiple APIs.

Entity Adapter Additions

adapter.removeMany now accepts a { where } object, and removes every entity whose fields match all the given values (#5524):

postsAdapter.removeMany(state, { where: { authorId: 5 } })

The match object is typed as Partial<T>, and values are compared with ===. A where object with no keys removes nothing, so a filter built at runtime that ends up empty can't clear the collection by accident. Use removeAll for that. There's also a new exported RemoveManyFilter<T> type.

getSelectors() now includes selectByIds(state, ids), which returns the entities for the given ids in the order of ids, skipping ids that don't exist.

removeMany is also faster. It used to filter the Immer draft of the ids array, which reads every element through the draft proxy. It now filters a plain copy against a Set of removed ids.

RTK Query Fixes

Lifecycles: cacheDataLoaded now only resolves for a response from a request that started while that lifecycle was waiting. A late response from before a removeQueryResult no longer resolves the next lifecycle on the same key with discarded data. Re-triggering a mutation with the same fixedCacheKey now ends the previous onCacheEntryAdded lifecycle, so its cacheEntryRemoved cleanup runs instead of leaking. If that earlier trigger is still in flight, its cacheDataLoaded now rejects instead of never settling. Thanks to @hamarshehmhmd for the analysis in #5539. getCacheEntry() in a mutation's onQueryStarted now finds the entry for fixedCacheKey mutations instead of always returning uninitialized.

Synchronous throws from onQueryStarted and onCacheEntryAdded are now caught and logged with console.error. Before, a sync throw in onQueryStarted escaped the pending dispatch and failed the request without ever calling queryFn. We also added a dev warning when updateCachedData is called before the entry has any data, since that call does nothing.

Polling: Polling now stops after the last unsubscribe even if the subscription cleanup hasn't run yet (thanks to @LeulTew for the original fix in #5444). A due poll re-reads skipPollingIfUnfocused instead of using the value from when the timer was set, and skips the poll if a request for that entry is already pending. pollingInterval values above 2^31-1 ms are now clamped with a dev warning, since larger values overflow setTimeout and fire after 1ms. Removing a cache entry with removeQueryResult now stops its poll timer right away, and switching a subscriber to a slower pollingInterval now reschedules the pending poll instead of letting the old, faster one fire once more. We also fixed a stale internal poll record that could block updatePollingInterval, and fetchBaseQuery now clears its timeout timer when the request finishes.

Upserts: A failed upsertQueryData over an existing entry (for example, from a responseSchema validation error) no longer leaves that entry stuck in pending. upsertQueryEntries now skips bad entries one at a time instead of failing the whole batch: unknown or mutation endpoint names and throwing providesTags callbacks are skipped, with dev warnings.

Timers and multiple stores: resetApiState now clears the subscription sync timer and the state for delayed tag invalidation, so work scheduled before the reset can't fire afterward. A keepUnusedDataFor removal timer is now cleared when the key gets a new subscriber or is removed with removeQueryResult, so an old timer can't remove a newer entry for the same key. Repeated initiate(arg, { subscribe: false }) calls that hit the cache no longer push back the keepUnusedDataFor removal, which could keep unused data around indefinitely (#4480, thanks @veksa!). setupListeners now works with more than one store. Before, only the first store got focus and online events.

Hooks: A query that failed before it ever got data now reports isLoading: true when it refetches, instead of having isLoading, isError and data all falsy while the request is pending (#4449, thanks @AnimeshPandey!). This undoes a change from 2.2.4 (#4364) that kept isLoading false when a second hook subscribed to an errored entry. If a parent renders null while isLoading is true and a child mounts the same query, the parent now unmounts the child on each refetch, and the two can loop. Render the child based on data or isError instead. Query args containing NaN no longer cause an endless refetch loop when the query errors. This was a regression from 2.9.0, where arg comparison treated NaN as never equal to itself (#5338, thanks @aagostino31!). fetchNextPage() and fetchPreviousPage() no longer send a request when the infinite query hook's arg is skipToken, and initiate(skipToken) no longer sends a request for any query or infinite query endpoint (#5028, thanks @haigou-web!).

fetchBaseQuery: A null body no longer throws Cannot read properties of null before the request is sent (thanks @dfedoryshchev!). An explicit content-type header is now kept for ArrayBuffer, typed array and Blob bodies, which broke presigned S3 and GCS uploads. It's still removed for FormData and for a JSON content type on a non-JSON body, and that JSON content type check is now case-insensitive (thanks @tad-bit-better!). A custom responseHandler that throws or rejects with a falsy value like undefined now produces a PARSING_ERROR, instead of being treated as a successful response (#5480, thanks @JunaidAhamed-7777!). A timeout that fires while the response body is being read is now reported as TIMEOUT_ERROR instead of PARSING_ERROR (thanks @Gurmehar-git!).

Other RTKQ fixes: An overlapping refetch now stays registered as the running query, so later calls join it and aborting it works (thanks @tedy69!). Apps with many createApi middlewares could hit a "Maximum call stack size exceeded" error when the middlewares registered themselves on the first query. Registration no longer restarts dispatch from the start of the middleware chain (thanks @PabloJoan!). api.enhanceEndpoints({ endpoints }) now logs an error in development when it names an endpoint that doesn't exist, which usually means a typo.

RTK Query thunk actions now include startedTimeStamp and a per-store seq counter in the fulfilled and rejected-with-value meta, matching the request's pending action, so you can tell which request a response belongs to and in what order requests started. Rejections for aborted requests and unhandled errors don't include these fields yet.

Other Fixes

The listener middleware's take(), condition() and delay() no longer leave their timers running after the listener is cancelled or the action arrives first.

The autoBatchEnhancer raf fallback no longer throws a cancelAnimationFrame ReferenceError in test environments that delete window globals during teardown (thanks @msutkowski!).

RTK Query hooks now log a dev warning when they render with a different store than the one they first subscribed to. If you swap the store passed to <Provider>, give the Provider a key that changes with the store so the tree remounts.

The serializability check middleware now reports a circular reference in state or actions as a non-serializable value, instead of overflowing the stack (thanks @OskarEichler!).

@types/react is now declared as an optional peer dependency. RTK's React entry points import React types, and with pnpm's isolated linker or a global virtual store, TypeScript couldn't find them and those types became any (thanks @unrevised6419!).

What's Changed

• fix(toolkit): cancelAnimationFrame ReferenceError in the autoBatch raf fallback by @msutkowski in fix(toolkit): cancelAnimationFrame ReferenceError in the autoBatch raf fallback #5462
• Add a dispatch-path benchmark harness by @markerikson in Add a dispatch-path benchmark harness #5537
• Fix listener take/delay timer leak and document isAnyOf matcher inference by @markerikson in Fix listener take/delay timer leak and document isAnyOf matcher inference #5538
• fix(query): keep overlapping refetches in the running query registry by @tedy69 in fix(query): keep overlapping refetches in the running query registry #5478
• Fix RTK Query polling timer bugs by @markerikson in Fix RTK Query polling timer bugs #5541
• Speed up removeMany in the entity adapter by @markerikson in Speed up removeMany in the entity adapter #5546
• Fix stuck pending after failed upsertQueryData, and skip bad upsertQueryEntries entries by @markerikson in Fix stuck pending after failed upsertQueryData, and skip bad upsertQueryEntries entries #5542
• Fix stale cacheDataLoaded, fixedCacheKey, getCacheEntry, and sync throws in RTKQ lifecycles by @markerikson in Fix stale cacheDataLoaded, fixedCacheKey, getCacheEntry, and sync throws in RTKQ lifecycles #5543
• Fix RTKQ middleware timer cleanup and setupListeners with multiple stores by @markerikson in Fix RTKQ middleware timer cleanup and setupListeners with multiple stores #5545
• Speed up RTKQ Api type checking by writing out the core module by @markerikson in Speed up RTKQ Api type checking by writing out the core module #5547
• Speed up the dispatch path in createAction, createReducer and listener middleware by @markerikson in Speed up the dispatch path in createAction, createReducer and listener middleware #5553
• Skip RTKQ reducer work for unhandled actions and unchanged provided tags by @markerikson in Skip RTKQ reducer work for unhandled actions and unchanged provided tags #5552
• Add removeMany({ where }) and selectByIds to entity adapter by @markerikson in Add removeMany({ where }) and selectByIds to entity adapter #5550
• Add startedTimeStamp and per-store seq to all RTKQ thunk meta by @markerikson in Add startedTimeStamp and per-store seq to all RTKQ thunk meta #5549
• Prevent registration of query middleware to restart dispatch from the beginning by @PabloJoan in Prevent registration of query middleware to restart dispatch from the beginning #5281
• End the previous cache lifecycle when a fixedCacheKey mutation is re-triggered by @markerikson in End the previous cache lifecycle when a fixedCacheKey mutation is re-triggered #5554
• Document keying the Provider when swapping stores, and warn in dev by @markerikson in Document keying the Provider when swapping stores, and warn in dev #5557
• Add enhanceEndpoints dev warning, query entry selectors, and createApiActionSanitizer by @markerikson in Add enhanceEndpoints dev warning, query entry selectors, and createApiActionSanitizer #5555
• Record RTKQ subscription sync patches directly and stop re-arming on non-subscribing requests by @markerikson in Record RTKQ subscription sync patches directly and stop re-arming on non-subscribing requests #5559
• Let esbuild tree-shake createAsyncThunk out of createSlice by @markerikson in Let esbuild tree-shake createAsyncThunk out of createSlice #5561
• Add RTK-owned Draft/Patch types, ApiRootState, listener action types, and hook result types by @markerikson in Add RTK-owned Draft/Patch types, ApiRootState, listener action types, and hook result types #5560
• Stop RTKQ polls when the cache entry is removed, and reschedule for slower intervals by @markerikson in Stop RTKQ polls when the cache entry is removed, and reschedule for slower intervals #5564
• fix(toolkit): don't treat a null body as jsonifiable in fetchBaseQuery by @dfedoryshchev in fix(toolkit): don't treat a null body as jsonifiable in fetchBaseQuery #5450
• Report circular serializable values without overflowing by @OskarEichler in Report circular serializable values without overflowing #5421
• fix(query): don't reset keepUnusedDataFor on condition-skipped queries by @veksa in fix(query): don't reset keepUnusedDataFor on condition-skipped queries #5343
• fix(toolkit): declare @types/react as an optional peer dependency by @unrevised6419 in fix(toolkit): declare @types/react as an optional peer dependency #5448
• Keep explicit content-type for binary bodies in fetchBaseQuery by @tad-bit-better in Keep explicit content-type for binary bodies in fetchBaseQuery #5479
• fix(toolkit): preserve falsy response handler errors by @JunaidAhamed-7777 in fix(toolkit): preserve falsy response handler errors #5481
• fix(toolkit): report response body timeouts as TIMEOUT_ERROR by @Gurmehar-git in fix(toolkit): report response body timeouts as TIMEOUT_ERROR #5482
• fix(toolkit): prevent infinite refetch loop when query args contain NaN by @aagostino31 in fix(toolkit): prevent infinite refetch loop when query args contain NaN #5339
• Fix isLoading staying false when refetching after an error with no data by @AnimeshPandey in Fix isLoading staying false when refetching after an error with no data #5470
• fix(toolkit): respect skipToken in infinite query triggers by @haigou-web in fix(toolkit): respect skipToken in infinite query triggers #5464

Full Changelog: v2.13.0...v2.14.0

---

This discussion was created from the release v2.14.0.