vue-query: `queryOptions()`'s real return type is unexported; the public name with the same identifier points at a different, legacy type

未關閉
#11,042 3 則留言 1 個 reaction 已指派 0 人 在 GitHub 檢視

維護者通常 1 天內回覆

@okxint 已經在處理了。

開始於 2026年11月9日。

  • #11098 來自 @ousamabenyounes —— 已關閉,未合併
  • #12568 來自 @okxint —— 未關閉

評估

難度
4/5
預估耗時
3-5 天
新手友好度
48/100
Issue 類型
缺陷
描述清晰度
基本清楚
活躍度
冷清
技術堆疊
typescript
領域
api, frontend

研究方向

先從 build/modern/_tsup-dts-rollup.d.ts 中已發布的宣告和 build/modern/index.d.ts 中的匯出開始,接著閱讀 queryOptions 的實作以及重現 repository 的 README.md。執行列出的 tsdown 和 tsc 重現;當宣告能在沒有 TS2527/TS2883 的情況下輸出,且下游的 select 組合保留正確的 query options 和 DataTag 型別時,即表示完成。

由索引模型根據 Issue 內容生成。

描述

Describe the bug

Since the 5.98.0 rewrite ("fix(vue-query): fix type of queryOptions to allow plain properties or getters"), queryOptions() is typed against a new QueryOptions-based shape. In the published rollup declaration file (build/modern/_tsup-dts-rollup.d.ts) this shape exists as UndefinedInitialQueryOptions_alias_1 / DefinedInitialQueryOptions_alias_1 — but:

  • _alias_1 is not exported from the package root (build/modern/index.d.ts).
  • The public names UndefinedInitialQueryOptions / DefinedInitialQueryOptions are re-exported from the root, but they still point at the old, UseQueryOptions-based, MaybeRef<...>-union type. Two genuinely different types share one exported name; only the wrong one is reachable.
  • Supporting types referenced by the new signature are unexported too: vue-query's ShallowOption, its local MaybeRefOrGetter alias, and query-core's QueryBehavior, RetryValue, RetryDelayValue, plus a non-exported unique symbol (dataTagErrorSymbol).

Any library that exports a function returning queryOptions(...) with an inferred return type — the exact pattern @kubb/plugin-vue-query generates for every endpoint — hits one of two consequences when its declarations are emitted:

  1. Hard declaration-emit errors (TS2527/TS2883) — reproduced here with both tsdown/rolldown-plugin-dts and plain tsc.
  2. Silently WRONG declarations — the natural fix for (1) is to annotate the return type with the public UndefinedInitialQueryOptions. That compiles with zero errors, but it is the wrong type: a consumer spreading the factory's result into another queryOptions() call to add select fails to type-check, and the DataTag on queryKey is lost.

Both are reproduced below, from the same root cause: the name collision.

Your minimal, reproducible example

https://github.com/DesselBane/repro-vue-query-query-options

Steps to reproduce

See repo README.md

Expected behavior

No TS2527 error and/or correct type exported so that downstream select works

How often does this bug happen?

Every time

Screenshots or Videos

No response

Platform
Package Version
@tanstack/vue-query 5.101.2 (also confirmed broken at 5.98.0; 5.97.0 is clean — see Regression window)
@tanstack/query-core 5.101.2 (transitive)
typescript 6.0.3
vue 3.5.31
tsdown 0.21.4 ([email protected], [email protected])
Node v24.0.0
OS Windows 11
Tanstack Query adapter

vue-query

TanStack Query version

5.98.0 (and 5.101.2)

TypeScript version

6.0.3

Additional context

Diagnosis and reproduction were created with the help of CLAUDE. I checked the repo and as far as I can tell this is all correct.

主要語言
TypeScript
星號
50.6k
分支
4.2k
平均合併
9 小時 50 分鐘
30 天內合併 PR
310

環境準備

從這裡開始

  1. 先讀完整個 Issue,再讀專案的貢獻指南。
  2. 在 Issue 下留言說明你要接手 —— 這能避免兩個人做同樣的事。
  3. Fork 儲存庫,在一個分支上完成修改。
  4. 送出 Pull Request,並在描述裡引用這個 Issue 編號。

TanStack/query 的其他 Issue

查看 TanStack/query 的全部 Issue

相似的 Issue

更多 TypeScript Issue

把新 issue 寄到你的電子郵件信箱

精選適合新手參與的 GitHub issue 摘要。