let’s do it again

packages/query-core/src/queryObserver.ts

@@ -582,6 +582,11 @@ export class QueryObserver<
       isRefetchError: isError && hasData,
       isStale: isStale(query, options),
       refetch: this.refetch,
+      promise: (prevQuery.promise ??
+        query.promise ??
+        new Promise(() => {
+          // never resolves? 🤷‍♂️
+        })) as any,
     }
 
     return result as QueryObserverResult<TData, TError>

packages/query-core/src/types.ts

@@ -661,6 +661,10 @@ export interface QueryObserverBaseResult<
    * - See [Network Mode](https://tanstack.com/query/latest/docs/framework/react/guides/network-mode) for more information.
    */
   fetchStatus: FetchStatus
+  /**
+   * A stable promise that will be resolved with the data of the query.
+   */
+  promise: Promise<TData>
 }
 
 export interface QueryObserverPendingResult<

packages/react-query/package.json

@@ -25,7 +25,7 @@
     "test:types:ts51": "node ../../node_modules/typescript51/lib/tsc.js -p tsconfig.legacy.json",
     "test:types:ts52": "node ../../node_modules/typescript52/lib/tsc.js -p tsconfig.legacy.json",
     "test:types:ts53": "tsc",
-    "test:lib": "vitest --retry=3",
+    "test:lib": "vitest",
     "test:lib:dev": "pnpm run test:lib --watch",
     "test:build": "publint --strict && attw --pack",
     "build": "pnpm build:tsup && pnpm build:codemods",

packages/react-query/src/__tests__/useQuery.test.tsx

@@ -41,6 +41,7 @@ describe('useQuery', () => {
       const fromQueryFn = useQuery({ queryKey: key, queryFn: () => 'test' })
       expectTypeOf(fromQueryFn.data).toEqualTypeOf<string | undefined>()
       expectTypeOf(fromQueryFn.error).toEqualTypeOf<Error | null>()
+      expectTypeOf(fromQueryFn.promise).toEqualTypeOf<Promise<string>>()
 
       // it should be possible to specify the result type
       const withResult = useQuery<string>({
@@ -6581,4 +6582,77 @@ describe('useQuery', () => {
 
     consoleMock.mockRestore()
   })
+
+  describe('useQuery().promise', () => {
+    it('should work with a basic test', async () => {
+      const key = queryKey()
+      let suspenseRenderCount = 0
+
+      function MyComponent(props: { promise: Promise<string> }) {
+        return <div>{React.use(props.promise)}</div>
+      }
+
+      function Loading() {
+        suspenseRenderCount++
+        return <>loading..</>
+      }
+      function Page() {
+        const query = useQuery({
+          queryKey: key,
+          queryFn: async () => {
+            await sleep(10)
+            return 'test'
+          },
+        })
+
+        return (
+          <React.Suspense fallback={<Loading />}>
+            <MyComponent promise={query.promise} />
+          </React.Suspense>
+        )
+      }
+
+      const rendered = renderWithClient(queryClient, <Page />)
+      await waitFor(() => rendered.getByText('loading..'))
+      await waitFor(() => rendered.getByText('test'))
+
+      // This should probably be 1 since `.promise` is the only "watched" property
+      // expect(suspenseRenderCount).toBe(1)
+    })
+  })
+
+  it('should work with initial data', async () => {
+    const key = queryKey()
+    let suspenseRenderCount = 0
+
+    function MyComponent(props: { promise: Promise<string> }) {
+      return <div>{React.use(props.promise)}</div>
+    }
+    function Loading() {
+      suspenseRenderCount++
+      return <>loading..</>
+    }
+    function Page() {
+      const query = useQuery({
+        queryKey: key,
+        queryFn: async () => {
+          await sleep(10)
+          return 'test'
+        },
+        initialData: 'initial',
+      })
+
+      return (
+        <React.Suspense fallback={<Loading />}>
+          <MyComponent promise={query.promise} />
+        </React.Suspense>
+      )
+    }
+
+    const rendered = renderWithClient(queryClient, <Page />)
+    await waitFor(() => rendered.getByText('initialData'))
+    await waitFor(() => rendered.getByText('test'))
+
+    expect(suspenseRenderCount).toBe(0)
+  })
 })