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

Aperta
#11,042 3 commenti 1 reazione 0 assegnatari Vedi su GitHub

I maintainer di solito rispondono entro 1 giorno

@okxint ci sta già lavorando.

Dal 9/11/2026.

  • #11098 di @ousamabenyounes — chiusa senza merge
  • #12568 di @okxint — aperta

Valutazione

Difficoltà
4/5
Tempo stimato
3-5 giorni
Idoneità per principianti
48/100
Tipo di issue
Bug
Chiarezza
Abbastanza chiara
Stato di attività
Tranquilla
Stack tecnologico
typescript
Ambito
api, frontend

Direzione di ricerca

Inizia con le dichiarazioni pubblicate in build/modern/_tsup-dts-rollup.d.ts e le esportazioni in build/modern/index.d.ts, quindi leggi l’implementazione di queryOptions e il README.md del repository di riproduzione. Esegui le riproduzioni elencate con tsdown e tsc; il lavoro è concluso quando le dichiarazioni vengono emesse senza TS2527/TS2883 e la composizione downstream di select conserva i tipi corretti di query options e DataTag.

Scritto dal modello di indicizzazione a partire dal testo della issue.

Descrizione

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.

Lingua principale
TypeScript
Stelle
50.6k
Fork
4.2k
Merge medio
9h 50m
PR unite (30g)
310

Preparare l'ambiente

Come iniziare

  1. Leggi tutta la issue e poi la guida ai contributi del progetto.
  2. Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
  3. Fai un fork del repository e lavora su un branch.
  4. Apri una pull request che faccia riferimento al numero della issue.

Altre issue di TanStack/query

Tutte le issue di TanStack/query

Issue simili

Altre issue su TypeScript

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.