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

Aberta
#11,042 3 comentários 1 reação 0 responsáveis Ver no GitHub

Mantenedores costumam responder em até 1 dia

@okxint já está trabalhando nisso.

Desde 9/11/2026.

  • #11098 de @ousamabenyounes — fechado sem integrar
  • #12568 de @okxint — aberto

Avaliação

Dificuldade
4/5
Tempo estimado
3-5 dias
Facilidade para iniciantes
48/100
Tipo de issue
Bug
Clareza
Razoavelmente clara
Status de atividade
Pouca atividade
Stack de tecnologia
typescript
Domínio
api, frontend

Direção de pesquisa

Comece pelas declarações publicadas em build/modern/_tsup-dts-rollup.d.ts e pelas exportações em build/modern/index.d.ts; depois, leia a implementação de queryOptions e o README.md do repositório de reprodução. Execute as reproduções listadas com tsdown e tsc; considera-se concluído quando as declarações forem emitidas sem TS2527/TS2883 e a composição downstream de select preservar os tipos corretos de query options e DataTag.

Escrita pelo modelo de indexação a partir do texto da issue.

Descrição

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.

Linguagem predominante
TypeScript
Estrelas
50.6k
Forks
4.2k
Merge médio
9h 50min
PRs com merge (30d)
310

Preparar o ambiente

Primeiros passos

  1. Leia a issue inteira e depois o guia de contribuição do projeto.
  2. Comente na issue dizendo que vai assumir — evita que duas pessoas façam o mesmo trabalho.
  3. Faça um fork do repositório e trabalhe em uma branch.
  4. Abra um pull request que referencie o número da issue.

Mais de TanStack/query

Todas as issues de TanStack/query

Issues semelhantes

Mais issues de TypeScript

Receba novas issues na sua caixa de entrada

Um resumo curto de issues do GitHub para quem está começando.