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 件 担当者 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 の実装と再現リポジトリの 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分
マージ済み PR(30日)
310

環境構築

はじめの一歩

  1. issue を最後まで読み、次にプロジェクトのコントリビューションガイドを読みます。
  2. 着手することを issue にコメントします — 二人が同じ作業をするのを防げます。
  3. リポジトリをフォークし、ブランチを切って変更します。
  4. issue 番号を参照したプルリクエストを送ります。

TanStack/query のほかの issue

TanStack/query の issue をすべて見る

似ている issue

TypeScript の issue をもっと見る

新しい issue をメールで受け取る

初心者向けの GitHub issue を短くまとめたダイジェスト。