feat: backport v5 apis to v4 #9140

manudeli · 2025-05-11T13:03:03Z

I added the v5 backport API to v4 based on the migration guide from migrating to v5 guide in TanStack Query Official Docs.

@tanstack/query-core

add MutationObserverBaseResult.isPending
tag keepPreviousData @deprecated
tag jsdoc @deprecated on unnecessary function overloads of QueryClient's methods -- isFetching, ensureQueryData, getQueriesData, setQueriesData, removeQueries, resetQueries, cancelQueries, invalidateQueries, refetchQueries, fetchQuery, prefetchQuery, fetchInfiniteQuery, prefetchInfiniteQuery
tag jsdoc @deprecated on unnecessary function overloads of QueryCache's methods -- find, findAll
- add function overloads for QueryCache.find(filters)
tag jsdoc @deprecated on unnecessary function overloads of useQuery, useInfiniteQuery

@tanstack/react-query

add queryOptions
add useSuspenseQuery
add useSuspenseQueries

@tanstack/vue-query

add function overloads for QueryCache.find(filters) like original QueryCache of @tanstack/query-core

I added test cases to guarantee all use cases with these apis backported

nx-cloud · 2025-05-11T13:03:49Z

View your CI Pipeline Execution ↗ for commit b907fd5.

Command	Status	Duration	Result
`nx affected --targets=test:eslint,test:lib,test...`	✅ Succeeded	1m 34s	View ↗
`nx affected --targets=test:lib --base=4e6432aed...`	✅ Succeeded	<1s	View ↗

☁️ Nx Cloud last updated this comment at 2025-05-25 17:14:04 UTC

codesandbox-ci · 2025-05-11T13:04:48Z

This pull request is automatically built and testable in CodeSandbox.

To see build info of the built libraries, click here or the icon next to each commit SHA.

Latest deployment of this branch, based on commit b907fd5:

Sandbox	Source
@tanstack/query-example-react-basic-typescript	Configuration
@tanstack/query-example-solid-basic-typescript	Configuration
@tanstack/query-example-svelte-basic	Configuration
@tanstack/query-example-vue-basic	Configuration

package.json

TkDodo · 2025-05-12T15:18:25Z

packages/react-query/src/queryOptions.ts

+    | 'getNextPageParam'
+    | 'getPreviousPageParam'
+    | 'queryKeyHashFn'
+    | '_defaulted'
+    | 'behavior'
+    | 'structuralSharing'
+    | 'isDataEqual'
+    | 'onSuccess'
+    | 'onError'
+    | 'onSettled'
+    | 'enabled'
+    | 'refetchInterval'
+    | 'initialData'
+    | 'networkMode'


we don’t have this in v5. Where is this list coming from ?

You're right — only 'getNextPageParam', 'getPreviousPageParam', 'onSuccess', 'onError', 'onSettled', and 'context' needed to be omitted here since these properties are no longer present in v5. When I copied the Suspensive React Query code, I didn't reconsider whether this list was still relevant, and ended up including some obsolete entries. Thanks for catching that! I reflect in 6c9d86f

Also, I should have omitted 'refetchInterval' as well. If we don’t, it can cause a TypeScript error like below. I was a bit sad to leave it out 🥲 — but I figured it’s not a big deal to omit it from queryOptions for now, as we can remove
omitting 'refetchInterval' next time if need.

Without Omit refetchInterval

With Omit refetchInterval

I'm going to explore some more to see if it's possible to support this without omitting refetchInterval. Will share back if I find a better workaround.

I explored a bit further to see if refetchInterval could be supported without breaking the v5 types, but unfortunately, I couldn’t find a viable workaround.

In v5, the refetchInterval function now receives only the Query object as its argument, whereas in v4 it used to receive both TData and Query. This change in signature makes it incompatible with v4-style callbacks. If we allow refetchInterval to pass through as-is, it could lead to subtle bugs or confusing TypeScript errors for users who are migrating and expect the old behavior.

Since the primary goal of queryOptions is to offer reusability and type safety across v5, I believe it’s better to leave refetchInterval out for now. Users who need it can still add it manually when configuring individual queries.

manudeli · 2025-05-18T17:35:24Z

packages/react-query/src/__tests__/queryOptions.types.test.tsx

+      expectTypeOf(query2).toEqualTypeOf<
+        DefinedUseQueryResult<{ field: string }>
+      >()
+      expectTypeOf(query3).toEqualTypeOf<
+        DefinedUseQueryResult<{ field: string }>
+      >()


Fixed the issue where useQueries had to return DefinedUseQueryResult.
This was previously returning UseQueryResult instead of DefinedUseQueryResult.

manudeli · 2025-05-18T17:36:05Z

packages/query-core/src/types.ts

@@ -256,6 +268,8 @@ export interface QueryObserverOptions<
  /**
   * Set this to `true` to keep the previous `data` when fetching based on a new query key.
   * Defaults to `false`.
+   *
+   * @deprecated keepPreviousData will be removed in the next major version.


Tagged @deprecated

manudeli · 2025-05-25T15:46:40Z

packages/query-core/src/queryClient.ts

+  /**
+   * @deprecated This method will accept only queryKey in the next major version.
+   */
+  getQueryData<TQueryFnData = unknown>(
+    queryKey: QueryKey,
+    filters: OmitKeyof<QueryFilters, 'queryKey'>,
+  ): TQueryFnData | undefined
+  /**
+   * @deprecated This method will accept only queryKey in the next major version.
+   */
+  getQueryData<TQueryFnData = unknown>(
+    queryKey: QueryKey,
+    filters?: OmitKeyof<QueryFilters, 'queryKey'>,


We can apply strikethrough to the unnecessary deprecated type overriding.

manudeli · 2025-05-25T16:00:27Z

packages/query-core/src/queryCache.ts

  find<TQueryFnData = unknown, TError = unknown, TData = TQueryFnData>(
-    arg1: QueryKey,
-    arg2?: QueryFilters,
+    filters: QueryFilters,
+  ): Query<TQueryFnData, TError, TData> | undefined


I added a function overload accepting only a filters object. This could make migration to v5 easier. In v5, QueryCache.find only accepts a filters object

manudeli · 2025-05-25T16:03:22Z

packages/query-core/src/queryCache.ts

+  /**
+   * @deprecated This method should be used with only one object argument.
+   */
+  find<TQueryFnData = unknown, TError = unknown, TData = TQueryFnData>(
+    queryKey: QueryKey,
+    filters?: OmitKeyof<QueryFilters, 'queryKey'>,
+  ): Query<TQueryFnData, TError, TData> | undefined
+  /**
+   * @deprecated This method should be used with only one object argument.
+   */
+  find<TQueryFnData = unknown, TError = unknown, TData = TQueryFnData>(
+    arg1: QueryKey | QueryFilters,
+    arg2?: OmitKeyof<QueryFilters, 'queryKey'>,


I tagged jsdoc @deprecated on unnecessary type overriding of QueryCache's methods

manudeli · 2025-05-25T16:03:59Z

packages/query-core/src/queryCache.ts

+  /**
+   * @deprecated This method should be used with only one object argument.
+   */
+  findAll(
+    queryKey?: QueryKey,
+    filters?: OmitKeyof<QueryFilters, 'queryKey'>,
+  ): Query[]
+  /**
+   * @deprecated This method should be used with only one object argument.
+   */
+  findAll(
+    arg1?: QueryKey | QueryFilters,
+    arg2?: OmitKeyof<QueryFilters, 'queryKey'>,
+  ): Query[]
+  /**
+   * @deprecated This method should be used with only one object argument.
+   */
+  findAll(
+    arg1?: QueryKey | QueryFilters,
+    arg2?: OmitKeyof<QueryFilters, 'queryKey'>,
+  ): Query[] {


I tagged jsdoc @deprecated on unnecessary type overriding of QueryCache's methods

manudeli · 2025-05-25T16:05:55Z

packages/query-core/src/mutationObserver.ts

+      isLoading,
+      isPending: isLoading,


We can use isPending like v5

manudeli · 2025-05-25T16:06:36Z

packages/query-core/src/queryClient.ts

+  /**
+   * @deprecated This method should be used with only one object argument.
+   */
+  isFetching(
+    queryKey?: QueryKey,
+    filters?: OmitKeyof<QueryFilters, 'queryKey'>,
+  ): number
+  /**
+   * @deprecated This method should be used with only one object argument.
+   */
  isFetching(arg1?: QueryKey | QueryFilters, arg2?: QueryFilters): number {


tag jsdoc @deprecated on unnecessary function overloads

Co-authored-by: Daniel Perez <[email protected]>

manudeli changed the title ~~feat(query-core, react-query): backport some v5 apis to v4~~ feat(query-core, react-query): backport v5 apis(useSuspenseQuery, useSuspenseQueries, queryOptions) to v4 May 11, 2025

manudeli changed the title ~~feat(query-core, react-query): backport v5 apis(useSuspenseQuery, useSuspenseQueries, queryOptions) to v4~~ feat(query-core, react-query): backport v5 apis(isPending, useSuspenseQuery, useSuspenseQueries, queryOptions) to v4 May 11, 2025

manudeli self-assigned this May 11, 2025

manudeli force-pushed the backport-v5-apis-to-v4 branch 2 times, most recently from d9085f6 to 98805c8 Compare May 11, 2025 13:28

manudeli commented May 11, 2025

View reviewed changes

package.json Show resolved Hide resolved

manudeli marked this pull request as ready for review May 11, 2025 13:57

manudeli requested a review from TkDodo May 11, 2025 13:58

TkDodo reviewed May 12, 2025

View reviewed changes

manudeli force-pushed the backport-v5-apis-to-v4 branch from 3ea3785 to 6c9d86f Compare May 12, 2025 16:35

manudeli marked this pull request as draft May 15, 2025 00:42

manudeli force-pushed the backport-v5-apis-to-v4 branch from 6c9d86f to 56487e6 Compare May 18, 2025 17:30

manudeli commented May 18, 2025

View reviewed changes

manudeli changed the title ~~feat(query-core, react-query): backport v5 apis(isPending, useSuspenseQuery, useSuspenseQueries, queryOptions) to v4~~ feat(query-core, react-query): backport v5 apis to v4 May 21, 2025

manudeli changed the title ~~feat(query-core, react-query): backport v5 apis to v4~~ feat(query-core, react-query, vue-query): backport v5 apis to v4 May 21, 2025

manudeli commented May 25, 2025

View reviewed changes

manudeli force-pushed the backport-v5-apis-to-v4 branch 2 times, most recently from 3a518d9 to ab6151b Compare May 25, 2025 15:52

manudeli commented May 25, 2025

View reviewed changes

manudeli force-pushed the backport-v5-apis-to-v4 branch 3 times, most recently from ab9aaf0 to d1698fa Compare May 25, 2025 17:05

manudeli changed the title ~~feat(query-core, react-query, vue-query): backport v5 apis to v4~~ feat: backport v5 apis to v4 May 25, 2025

feat: backport v5 apis to v4

b907fd5

Co-authored-by: Daniel Perez <[email protected]>

manudeli force-pushed the backport-v5-apis-to-v4 branch from d1698fa to b907fd5 Compare May 25, 2025 17:11

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!

feat: backport v5 apis to v4 #9140

feat: backport v5 apis to v4 #9140

manudeli commented May 11, 2025 •

edited

Loading

Uh oh!

nx-cloud bot commented May 11, 2025 •

edited

Loading

Uh oh!

codesandbox-ci bot commented May 11, 2025 •

edited

Loading

Uh oh!

Uh oh!

TkDodo May 12, 2025

Uh oh!

manudeli May 12, 2025 •

edited

Loading

Uh oh!

manudeli May 14, 2025

Uh oh!

manudeli May 25, 2025

Uh oh!

manudeli May 18, 2025 •

edited

Loading

Uh oh!

manudeli May 18, 2025

Uh oh!

manudeli May 25, 2025

Uh oh!

manudeli May 25, 2025 •

edited

Loading

Uh oh!

manudeli May 25, 2025 •

edited

Loading

Uh oh!

manudeli May 25, 2025

Uh oh!

manudeli May 25, 2025

Uh oh!

manudeli May 25, 2025

Uh oh!

Uh oh!

Uh oh!

feat: backport v5 apis to v4 #9140

Are you sure you want to change the base?

feat: backport v5 apis to v4 #9140

Conversation

manudeli commented May 11, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

@tanstack/query-core

@tanstack/react-query

@tanstack/vue-query

Uh oh!

nx-cloud bot commented May 11, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

codesandbox-ci bot commented May 11, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

manudeli May 12, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Without Omit refetchInterval

With Omit refetchInterval

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

manudeli May 18, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

manudeli May 25, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

manudeli May 25, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

manudeli commented May 11, 2025 •

edited

Loading

nx-cloud bot commented May 11, 2025 •

edited

Loading

codesandbox-ci bot commented May 11, 2025 •

edited

Loading

manudeli May 12, 2025 •

edited

Loading

manudeli May 18, 2025 •

edited

Loading

manudeli May 25, 2025 •

edited

Loading

manudeli May 25, 2025 •

edited

Loading