npm @reduxjs/toolkit 2.15.0
v2.15.0

one hour ago

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's reset(), cache collection, and resetApiState. The initiate() promise resolves with isError: true and an AbortError whose message is 'removed' or 'reset'. That means unwrap() now rejects in this case, where it used to resolve with stale or missing data. The plain promise still never rejects.

  • queryFulfilled in onQueryStarted rejects in the same case. If your onQueryStarted does await queryFulfilled without a try/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 running upsertQueryData.

  • A pending entry 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 pollingInterval now means "no polling". Before, it re-polled immediately in a loop.
  • 'payload.options.pollingInterval' is a new default entry in the serializability check's ignoredActionPaths. If you pass your own ignoredActionPaths, you'll need to add it.
  • SubscriptionOptions['pollingInterval'] is now number | ((entry) => number), so code that reads it as a number needs a type check. There's a new exported PollingInterval type.

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 (currently getSubscriptionCount(queryCacheKey)), or undefined if the middleware isn't added (#5501).
  • Query initiate() results have an isSubscribed() 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: 0 and forceRefetch: 0 now always refetch. Before, 0 disabled the option.
  • refetchOnFocus and refetchOnReconnect refetch a shared query if any subscriber's own or inherited setting is true. One subscriber's false no 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, and fork to ForkedTaskAPI by @markerikson in #5572
  • Fix public type names shown in editor hovers (Slice$1, IsAny) by @markerikson in #5575
  • Add api.util.getMiddlewareState() and isSubscribed() on query initiate() 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 startReason to BaseQueryApi and query lifecycle APIs by @markerikson in #5601
  • Add endpoint.getRunningQuery and initiate retainFor option by @markerikson in #5602
  • Allow pollingInterval to be a function of the cache entry by @markerikson in #5604
  • fix(toolkit): keep prepare parameter types when wrapping createSlice by @kkatalz in #5591
  • fix(entityAdapter): keep ids order when an update changes an entity id by @b84330808 in #5573
  • fix(toolkit): fetchBaseQuery timeouts 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 a backoff function 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

Don't miss a new toolkit release

NewReleases is sending notifications on new releases.