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

Offen
#11,042 3 Kommentare 1 Reaktion 0 zugewiesene Personen Auf GitHub ansehen

Maintainer antworten meist innerhalb von 1 Tag

@okxint arbeitet bereits daran.

Seit 09.11.2026.

  • #11098 von @ousamabenyounes — ohne Merge geschlossen
  • #12568 von @okxint — offen

Bewertung

Schwierigkeit
4/5
Geschätzter Aufwand
3-5 Tage
Anfängerfreundlichkeit
48/100
Issue-Typ
Bug
Klarheit
Größtenteils klar
Aktivitätsstatus
Ruhig
Tech-Stack
typescript
Bereich
api, frontend

Rechercherichtung

Beginne mit den veröffentlichten Deklarationen in build/modern/_tsup-dts-rollup.d.ts und den Exporten in build/modern/index.d.ts, lies anschließend die Implementierung von queryOptions und die README.md des Reproduktions-Repositorys. Führe die aufgeführten Reproduktionen mit tsdown und tsc aus; abgeschlossen bedeutet, dass die Deklarationen ohne TS2527/TS2883 ausgegeben werden und die Komposition von select im Downstream die korrekten query options- und DataTag-Typen beibehält.

Vom Indexierungsmodell aus dem Issue-Text verfasst.

Beschreibung

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.

Vorherrschende Sprache
TypeScript
Sterne
50.6k
Forks
4.2k
Ø Merge
9 Std. 50 Min.
Gemergte PRs (30 T.)
310

Entwicklungsumgebung

Erste Schritte

  1. Lesen Sie das ganze Issue und danach den Beitragsleitfaden des Projekts.
  2. Schreiben Sie ins Issue, dass Sie es übernehmen — das erspart doppelte Arbeit.
  3. Forken Sie das Repository und arbeiten Sie in einem Branch.
  4. Öffnen Sie einen Pull Request, der die Issue-Nummer nennt.

Mehr aus TanStack/query

Alle Issues in TanStack/query

Ähnliche Issues

Weitere Issues zu TypeScript

Neue Issues direkt in Ihr Postfach

Eine kurze Übersicht über anfängerfreundliche GitHub-Issues.