Repository navigation
v2.15.0 #5623
markerikson
announced in
Announcements
v2.15.0
#5623
Replies: 0 comments
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Uh oh!
There was an error while loading. Please reload this page.
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
apiobject. That was fine for a single client-side store, but caused problems for SSR and tests, where many stores share oneapi.Each store now gets its own consolidated internal runtime state, created by the API middleware.
resetApiStatenow callsruntime.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
reducerPathhas its middleware in the store.initiate()Promises Resolve With Their Own ResultWe had several long-standing reports (#5506, #4833, #5173, #5346) that the promise from
initiate()could resolve withundefined, 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'sfulfilledorrejectedaction 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: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.onCacheEntryAddedhas a newgetCacheEntryRemovedReason()function that returns'reset'if the entry was removed byresetApiState,'removed'for any other removal, orundefinedwhile the entry is still in the cache.cacheEntryRemovedstays aPromise<void>, since many apps declare that type in their own handler types.startReasonfor Query RequestsWe've had a request (#4757) to know why a query is fetching. For example, a
queryFnmight want to read from the primary database after a tag invalidation, instead of a replica that may be behind.baseQuery/queryFn(viaBaseQueryApi),fetchBaseQuery'sprepareHeaders,onQueryStartedandonCacheEntryAddednow receive astartReason. The newQueryStartReasontype is'initial' | 'refetch' | 'invalidation' | 'poll' | 'focus' | 'reconnect' | 'upsert' | 'hydrate' | 'nextPage' | 'previousPage'.A few details:
'initial'vs'refetch'depends on whether the entry already has data. Mutations getstartReason: undefined.'hydrate'is reserved for upcoming hydration work and isn't set yet. We may add additional values in the future if needed.Function
pollingIntervalpollingIntervalcan 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:It works in all the query hooks,
initiate()andupdateSubscriptionOptions. 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. Returning0, 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 dispatchupdateSubscriptionOptionson every render.Related changes:
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.getRunningQueryandretainForapi.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, orundefined. It's the same promise theinitiate()call that started the request returned, and awaiting it doesn't add a subscription. It's the typed per-endpoint form ofapi.util.getRunningQueryThunk.Query
initiate()has a newretainForoption, in seconds. After the last subscriber leaves, the entry is kept forMath.max(keepUnusedDataFor, retainFor)seconds. This is useful for prefetching orsubscribe: falserequests whose data will be read soon: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()whilefetchPreviousPage()is running. The second call still joins and doesn't fetch its own page, same as before.getMiddlewareState()andisSubscribed()The React hooks used to dispatch an internal
internal_getRTKQSubscriptionsaction 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).initiate()results have anisSubscribed()method.The hooks use
isSubscribed()now, and don't dispatch anything to check subscriptions. Theinternal_getRTKQSubscriptionsaction 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 togetMiddlewareState()andisSubscribed().The hooks also no longer run their own missing-middleware check. A hook with
skip: trueon a store without the API middleware no longer throws. A non-skipped hook still throws, from the check ininitiate().Listener Middleware: Nested Forks
ForkedTaskAPInow hasgetState,dispatchandfork, 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 withautoJoin: truemakes its parent wait for it before completing.ForkedTaskAPIand the task executor types have optionalStateandDispatchTypegenerics, which flow throughstartListening,addListenerand theirwithTypes()versions. Like the listener's owngetStateanddispatch, 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$1andIsAny. We've added named types so hovers show a name instead of the full structure:FetchBaseQueryFn,ApiUtil,ListenerMiddlewareDispatch,AsyncThunkPromiseandReactApiModules. The query, mutation and infinite query selector result types were rewritten so TypeScript keeps their names. Some hover lengths, before and after:useMutationtupleendpoints.getPost.select(...)api.utildispatch(thunk(...))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.skipPollingIfUnfocused. Non-polling subscribers don't affect this.Thanks to @duckieeeduck for this fix!
Other Fixes
An endpoint's
maxRetriesnow caps retries even when the api-levelretry()has aretryCondition. TheretryConditionstill decides which errors retry (thanks @luantaraschi!).retry.fail()called inside abackofffunction no longer nests the error inside{ error, meta }(thanks @dfedoryshchev!).fetchBaseQuery'stimeoutnow works when the request passes its ownsignal(thanks @wozhenbang2004!). Query parameters are now added before a URL#fragmentinstead of after it (thanks @henricop!).FetchArgs.headersnow acceptsnumberandbooleanvalues, which are converted to strings. They already worked at runtime (thanks @emersion!).The entity adapter keeps the
idsorder when an update changes an entity's id (thanks @b84330808!).Wrapping
createSlicein a generic helper now keeps thepreparecallback's parameter types (thanks @kkatalz!).Docs Updates
We've documented
getCacheEntryRemovedReason,startReason,getRunningQuery,retainFor,getMiddlewareState,isSubscribed, functionpollingIntervaland nested forks, and fixed several smaller doc and JSDoc errors.What's Changed
reset()by @markerikson in Give each store its own RTKQ middleware runtime, withreset()#5570getState,dispatch, andforktoForkedTaskAPIby @markerikson in AddgetState,dispatch, andforktoForkedTaskAPI#5572Slice$1,IsAny) by @markerikson in Fix public type names shown in editor hovers (Slice$1,IsAny) #5575api.util.getMiddlewareState()andisSubscribed()on queryinitiate()results by @markerikson in Addapi.util.getMiddlewareState()andisSubscribed()on queryinitiate()results #5579initiate()promises with their own request result, and remove entries through one path by @markerikson in Resolveinitiate()promises with their own request result, and remove entries through one path #5587startReasontoBaseQueryApiand query lifecycle APIs by @markerikson in AddstartReasontoBaseQueryApiand query lifecycle APIs #5601endpoint.getRunningQueryandinitiateretainForoption by @markerikson in Addendpoint.getRunningQueryandinitiateretainForoption #5602pollingIntervalto be a function of the cache entry by @markerikson in AllowpollingIntervalto be a function of the cache entry #5604prepareparameter types when wrappingcreateSliceby @kkatalz in fix(toolkit): keepprepareparameter types when wrappingcreateSlice#5591fetchBaseQuerytimeouts when a request provides a signal by @wozhenbang2004 in fix(toolkit):fetchBaseQuerytimeouts when a request provides a signal #5595retry.fail()in abackofffunction nesting the error in{ error, meta }by @dfedoryshchev in fix(toolkit):retry.fail()in abackofffunction nesting the error in{ error, meta }#5612Full Changelog: v2.14.0...v2.15.0
This discussion was created from the release v2.15.0.
All reactions