From d8e00a7e0df4f39aa905e25323fa2e45f7d25d5c Mon Sep 17 00:00:00 2001
From: Ben Younes <2910651+ousamabenyounes@users.noreply.github.com>
Date: Wed, 23 Sep 2026 23:41:36 +0000
Subject: [PATCH] fix(vue-query): export queryOptions support types (#11042)

Re-export the helper types that the public queryOptions signature depends
on but that were unreachable from the package roots: ShallowOption and
MaybeRefOrGetter from @tanstack/vue-query, and QueryBehavior, RetryValue,
RetryDelayValue from @tanstack/query-core. The declaration-emit / name
collision core of #11042 was already fixed by #11224; this completes the
remaining unexported-supporting-types part.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 .changeset/export-queryoptions-support-types.md     | 13 +++++++++++++
 .../src/__tests__/publicTypeExports.test-d.ts       | 13 +++++++++++++
 packages/query-core/src/index.ts                    |  2 ++
 .../src/__tests__/publicTypeExports.test-d.ts       | 12 ++++++++++++
 packages/vue-query/src/index.ts                     |  2 +-
 5 files changed, 41 insertions(+), 1 deletion(-)
 create mode 100644 .changeset/export-queryoptions-support-types.md
 create mode 100644 packages/query-core/src/__tests__/publicTypeExports.test-d.ts
 create mode 100644 packages/vue-query/src/__tests__/publicTypeExports.test-d.ts

diff --git a/.changeset/export-queryoptions-support-types.md b/.changeset/export-queryoptions-support-types.md
new file mode 100644
index 00000000000..fd8d8697988
--- /dev/null
+++ b/.changeset/export-queryoptions-support-types.md
@@ -0,0 +1,13 @@
+---
+'@tanstack/query-core': patch
+'@tanstack/vue-query': patch
+---
+
+fix(vue-query): export the helper types referenced by `queryOptions`
+
+Re-export from the package roots the supporting types that the public
+`queryOptions` signature depends on but that were previously unreachable:
+`ShallowOption` and `MaybeRefOrGetter` from `@tanstack/vue-query`, and
+`QueryBehavior`, `RetryValue` and `RetryDelayValue` from `@tanstack/query-core`.
+This lets downstream libraries name the inferred `queryOptions` return type in
+their emitted declarations (#11042).
diff --git a/packages/query-core/src/__tests__/publicTypeExports.test-d.ts b/packages/query-core/src/__tests__/publicTypeExports.test-d.ts
new file mode 100644
index 00000000000..41421d50718
--- /dev/null
+++ b/packages/query-core/src/__tests__/publicTypeExports.test-d.ts
@@ -0,0 +1,13 @@
+import { describe, expectTypeOf, it } from 'vitest'
+import type { QueryBehavior, RetryDelayValue, RetryValue } from '..'
+
+// Regression for #11042: the types referenced by the public `queryOptions`
+// signature must be reachable from the package root, otherwise downstream
+// declaration emit cannot name them.
+describe('public type exports', () => {
+  it('re-exports retry and behavior helper types from the package root', () => {
+    expectTypeOf<RetryValue<Error>>().not.toBeNever()
+    expectTypeOf<RetryDelayValue<Error>>().not.toBeNever()
+    expectTypeOf<QueryBehavior>().not.toBeNever()
+  })
+})
diff --git a/packages/query-core/src/index.ts b/packages/query-core/src/index.ts
index 7d9dd23379f..b2e19ac2e30 100644
--- a/packages/query-core/src/index.ts
+++ b/packages/query-core/src/index.ts
@@ -23,6 +23,8 @@ export type { QueryCacheNotifyEvent } from './queryCache'
 export { QueryClient } from './queryClient'
 export { QueryObserver } from './queryObserver'
 export { CancelledError, isCancelledError } from './retryer'
+export type { RetryDelayValue, RetryValue } from './retryer'
+export type { QueryBehavior } from './query'
 export {
   timeoutManager,
   type ManagedTimerId,
diff --git a/packages/vue-query/src/__tests__/publicTypeExports.test-d.ts b/packages/vue-query/src/__tests__/publicTypeExports.test-d.ts
new file mode 100644
index 00000000000..08f5d313368
--- /dev/null
+++ b/packages/vue-query/src/__tests__/publicTypeExports.test-d.ts
@@ -0,0 +1,12 @@
+import { describe, expectTypeOf, it } from 'vitest'
+import type { MaybeRefOrGetter, ShallowOption } from '..'
+
+// Regression for #11042: the vue-query helper types referenced by the public
+// `queryOptions` signature must be reachable from the package root so that
+// downstream declaration emit can name them.
+describe('public type exports', () => {
+  it('re-exports vue-query helper types from the package root', () => {
+    expectTypeOf<ShallowOption>().not.toBeNever()
+    expectTypeOf<MaybeRefOrGetter<number>>().not.toBeNever()
+  })
+})
diff --git a/packages/vue-query/src/index.ts b/packages/vue-query/src/index.ts
index 34f8d48819a..df9e43f15c4 100644
--- a/packages/vue-query/src/index.ts
+++ b/packages/vue-query/src/index.ts
@@ -39,7 +39,7 @@ export type {
   UseInfiniteQueryReturnType,
 } from './useInfiniteQuery'
 export type { UseMutationOptions, UseMutationReturnType } from './useMutation'
-export type { MutationOptions } from './types'
+export type { MaybeRefOrGetter, MutationOptions, ShallowOption } from './types'
 export type { UseQueriesOptions, UseQueriesResults } from './useQueries'
 export type {
   MutationStateOptions,