Repository navigation
This feature release gives each store its own RTK Query middleware runtime, makes initiate() promises resolve with their own request's result, adds several new options to RTK Query, improves listener middleware fork child capabilities, improves readability for several RTK type definitions, and fixes a variety of RTKQ bugs.
This release continues the work from our roadmap to Redux Toolkit 3.0. Several of the RTK Query changes here are bug fixes that change behavior in edge cases, so please read the "Behavior Changes" notes below.
Changelog
Per-Store RTK Query Runtime
RTK Query's middleware keeps a lot of state outside the Redux store in order to manage requests and cache lifetimes: subscriber counts, running requests, poll and cache collection timers, and cache lifecycle promises. That state used to live in closures shared by every store that used the same api object. That was fine for a single client-side store, but caused problems for SSR and tests, where many stores share one api.
Each store now gets its own consolidated internal runtime state, created by the API middleware. resetApiState now calls runtime.reset(), which clears every subscriber, timer and cache lifecycle for that store, aborts running requests, and clears pending tag invalidations. It no longer touches other stores.
Internally, each cache key now has one record that tracks its running request, timers and lifecycle, and all removals go through a single path. That made the initiate() fixes below possible.
The missing-middleware check now runs once per store, and looks for the store's runtime instead of dispatching an internal action. This check is stricter: an api whose middleware is missing now throws even if another api with the same reducerPath has its middleware in the store.
initiate() Promises Resolve With Their Own Result
We had several long-standing reports (#5506, #4833, #5173, #5346) that the promise from initiate() could resolve with undefined, or with a different request's data. That happened when the cache entry was removed, reset, invalidated or replaced while the request was running, because the promise read the cache entry after the request finished instead of the request's own result.
We've done a thorough review of the promise resolution logic to analyze the current intended behavior, ran separate formal modeling of the derived behavior to help uncover gaps, updated the model to fill those gaps, and reworked that logic to fully comply with the improved expected behavior.
Each initiate() promise now resolves with its own request's result, captured as soon as that request's fulfilled or rejected action reaches the store.
Thanks to @kkatalz (#5474) and @rajanpanth (#5347): both PRs fixed part of this, and their tests are included.
Behavior Changes
These ship in 2.x as bug fixes, but code that depended on the old behavior will see a difference:
-
Removing a cache entry while its request runs now aborts that request. This covers
removeQueryResult, a lazy query'sreset(), cache collection, andresetApiState. Theinitiate()promise resolves withisError: trueand anAbortErrorwhose message is'removed'or'reset'. That meansunwrap()now rejects in this case, where it used to resolve with stale or missing data. The plain promise still never rejects. -
queryFulfilledinonQueryStartedrejects in the same case. If youronQueryStarteddoesawait queryFulfilledwithout atry/catch, you'll now get an unhandled rejection when the entry is removed mid-request. Wrap it:async onQueryStarted(arg, { queryFulfilled }) { try { const { data } = await queryFulfilled // ... } catch { // request failed, or the cache entry was removed while it ran } }
-
Invalidating an entry that has a running request (by tags, or a focus/reconnect refetch) now waits for that request to finish. The running request's promise gets its own result, and then the entry refetches if it has subscribers, or is removed if it doesn't.
-
A refetch while a request is running joins that request instead of starting another one.
initiate()also joins a runningupsertQueryData. -
A
pendingentry restored from persisted state, with no request actually running, now fetches again.
onCacheEntryAdded has a new getCacheEntryRemovedReason() function that returns 'reset' if the entry was removed by resetApiState, 'removed' for any other removal, or undefined while the entry is still in the cache. cacheEntryRemoved stays a Promise<void>, since many apps declare that type in their own handler types.
async onCacheEntryAdded(arg, { cacheEntryRemoved, getCacheEntryRemovedReason }) {
const connection = openConnection(arg)
await cacheEntryRemoved
if (getCacheEntryRemovedReason() !== 'reset') {
connection.unsubscribe()
}
connection.close()
}startReason for Query Requests
We've had a request (#4757) to know why a query is fetching. For example, a queryFn might want to read from the primary database after a tag invalidation, instead of a replica that may be behind.
baseQuery / queryFn (via BaseQueryApi), fetchBaseQuery's prepareHeaders, onQueryStarted and onCacheEntryAdded now receive a startReason. The new QueryStartReason type is 'initial' | 'refetch' | 'invalidation' | 'poll' | 'focus' | 'reconnect' | 'upsert' | 'hydrate' | 'nextPage' | 'previousPage'.
const api = createApi({
baseQuery: fetchBaseQuery({
baseUrl: '/api',
prepareHeaders: (headers, { startReason }) => {
if (startReason === 'invalidation') {
headers.set('x-read-from-primary', 'true')
}
return headers
},
}),
endpoints: () => ({}),
})A few details: 'initial' vs 'refetch' depends on whether the entry already has data. Mutations get startReason: undefined. 'hydrate' is reserved for upcoming hydration work and isn't set yet. We may add additional values in the future if needed.
Function pollingInterval
pollingInterval can now be a function that receives the current cache entry and returns an interval in ms (#2639). This covers "poll while a job is running, stop when it's done" without a second hook:
useGetJobQuery(id, {
pollingInterval: ({ data }) => (data?.status === 'running' ? 1000 : 0),
})It works in all the query hooks, initiate() and updateSubscriptionOptions. The function runs once per cache key when the next poll is scheduled after a request settles. When several subscribers poll the same key, the lowest result wins, the same as numeric intervals. Returning 0, a negative number or a non-number means "don't poll", and polling resumes if a later request makes the function return an interval again. An inline function in a hook doesn't dispatch updateSubscriptionOptions on every render.
Related changes:
- A negative numeric
pollingIntervalnow means "no polling". Before, it re-polled immediately in a loop. 'payload.options.pollingInterval'is a new default entry in the serializability check'signoredActionPaths. If you pass your ownignoredActionPaths, you'll need to add it.SubscriptionOptions['pollingInterval']is nownumber | ((entry) => number), so code that reads it as anumberneeds a type check. There's a new exportedPollingIntervaltype.
getRunningQuery and retainFor
api.endpoints.x.getRunningQuery(arg) is a typed thunk for query and infinite query endpoints. Dispatching it returns the promise of the running request for that cache entry, or undefined. It's the same promise the initiate() call that started the request returned, and awaiting it doesn't add a subscription. It's the typed per-endpoint form of api.util.getRunningQueryThunk.
Query initiate() has a new retainFor option, in seconds. After the last subscriber leaves, the entry is kept for Math.max(keepUnusedDataFor, retainFor) seconds. This is useful for prefetching or subscribe: false requests whose data will be read soon:
dispatch(api.endpoints.getPost.initiate(id, { subscribe: false, retainFor: 60 }))
// later
const running = dispatch(api.endpoints.getPost.getRunningQuery(id))
if (running) {
await running
}There's also a new dev-only warning when an infinite query page fetch joins a running fetch in the other direction, like calling fetchNextPage() while fetchPreviousPage() is running. The second call still joins and doesn't fetch its own page, same as before.
getMiddlewareState() and isSubscribed()
The React hooks used to dispatch an internal internal_getRTKQSubscriptions action to check subscription status, and some libraries copied that pattern. We've added real APIs for it:
api.util.getMiddlewareState()is a thunk that returns read-only access to what the middleware tracks for that store (currentlygetSubscriptionCount(queryCacheKey)), orundefinedif the middleware isn't added (#5501).- Query
initiate()results have anisSubscribed()method.
The hooks use isSubscribed() now, and don't dispatch anything to check subscriptions. The internal_getRTKQSubscriptions action is deprecated. It still works in 2.x, but logs a one-time dev warning and will be removed in 3.0. If you maintain a library that dispatches it (such as a port of the RTKQ hooks to another framework), switch to getMiddlewareState() and isSubscribed().
The hooks also no longer run their own missing-middleware check. A hook with skip: true on a store without the API middleware no longer throws. A non-skipped hook still throws, from the check in initiate().
Listener Middleware: Nested Forks
ForkedTaskAPI now has getState, dispatch and fork, so a forked task can read state, dispatch actions and start its own child tasks (#3314). Nested forks are cancelled when the task that forked them ends or is cancelled. A nested fork with autoJoin: true makes its parent wait for it before completing.
listenerMiddleware.startListening({
actionCreator: startSync,
effect: async (action, listenerApi) => {
listenerApi.fork(async (forkApi) => {
const { userId } = forkApi.getState().auth
forkApi.fork(
async (childApi) => {
childApi.dispatch(syncStarted(userId))
},
{ autoJoin: true },
)
})
},
})ForkedTaskAPI and the task executor types have optional State and DispatchType generics, which flow through startListening, addListener and their withTypes() versions. Like the listener's own getState and dispatch, these aren't guarded after the task finishes. With some internal cleanup in the same PR, the listener middleware is slightly smaller even with the new API.
Readable Editor Hovers
Hovering over RTK and RTKQ types in an editor often showed a wall of text that the editor cut off at 500 characters, along with odd names like Slice$1 and IsAny. We've added named types so hovers show a name instead of the full structure: FetchBaseQueryFn, ApiUtil, ListenerMiddlewareDispatch, AsyncThunkPromise and ReactApiModules. The query, mutation and infinite query selector result types were rewritten so TypeScript keeps their names. Some hover lengths, before and after:
| Hover | Before | After |
|---|---|---|
useMutation tuple |
2508 | 386 |
endpoints.getPost.select(...) |
2399 | 602 |
api.util |
16102 | 471 |
dispatch(thunk(...)) |
552 | 71 |
These are type-only changes. Please let us know if the selector result rewrite causes problems in code that's generic over endpoint definitions.
Refetch and Polling Option Fixes
When several subscribers share a query, RTKQ combines their options. Some of those rules skipped refetches that a subscriber asked for (#5583). Each subscriber's options are now resolved before they're combined:
refetchOnMountOrArgChange: 0andforceRefetch: 0now always refetch. Before,0disabled the option.refetchOnFocusandrefetchOnReconnectrefetch a shared query if any subscriber's own or inherited setting istrue. One subscriber'sfalseno longer turns it off for the others.- Polling skips while unfocused only if every polling subscriber sets
skipPollingIfUnfocused. Non-polling subscribers don't affect this.
Thanks to @duckieeeduck for this fix!
Other Fixes
An endpoint's maxRetries now caps retries even when the api-level retry() has a retryCondition. The retryCondition still decides which errors retry (thanks @luantaraschi!).
retry.fail() called inside a backoff function no longer nests the error inside { error, meta } (thanks @dfedoryshchev!).
fetchBaseQuery's timeout now works when the request passes its own signal (thanks @wozhenbang2004!). Query parameters are now added before a URL #fragment instead of after it (thanks @henricop!). FetchArgs.headers now accepts number and boolean values, which are converted to strings. They already worked at runtime (thanks @emersion!).
The entity adapter keeps the ids order when an update changes an entity's id (thanks @b84330808!).
Wrapping createSlice in a generic helper now keeps the prepare callback's parameter types (thanks @kkatalz!).
Docs Updates
We've documented getCacheEntryRemovedReason, startReason, getRunningQuery, retainFor, getMiddlewareState, isSubscribed, function pollingInterval and nested forks, and fixed several smaller doc and JSDoc errors.
What's Changed
- Refactor RTKQ middleware state into a per-store runtime by @markerikson in #5569
- Give each store its own RTKQ middleware runtime, with
reset()by @markerikson in #5570 - Add
getState,dispatch, andforktoForkedTaskAPIby @markerikson in #5572 - Fix public type names shown in editor hovers (
Slice$1,IsAny) by @markerikson in #5575 - Add
api.util.getMiddlewareState()andisSubscribed()on queryinitiate()results by @markerikson in #5579 - Track each cache key's request, timers and lifecycle through record transitions by @markerikson in #5586
- Resolve
initiate()promises with their own request result, and remove entries through one path by @markerikson in #5587 - Settle and abort every running request for a key when its entry is removed by @markerikson in #5589
- Add named public types so editor hovers stay readable by @markerikson in #5576
- Fix endpoint maxRetries being ignored with a retry() retryCondition by @luantaraschi in #5590
- Add
startReasontoBaseQueryApiand query lifecycle APIs by @markerikson in #5601 - Add
endpoint.getRunningQueryandinitiateretainForoption by @markerikson in #5602 - Allow
pollingIntervalto be a function of the cache entry by @markerikson in #5604 - fix(toolkit): keep
prepareparameter types when wrappingcreateSliceby @kkatalz in #5591 - fix(entityAdapter): keep ids order when an update changes an entity id by @b84330808 in #5573
- fix(toolkit):
fetchBaseQuerytimeouts when a request provides a signal by @wozhenbang2004 in #5595 - Fix refetch defaults and shared polling preferences by @duckieeeduck in #5593
- fix(toolkit):
retry.fail()in abackofffunction nesting the error in{ error, meta }by @dfedoryshchev in #5612 - fix(query): append query parameters before URL fragments by @henricop in #5598
- fix(query): allow boolean/number in headers by @emersion in #5621
Full Changelog: v2.14.0...v2.15.0