Skip to content

fix query option declaration emit#10583

Open
artemxknpv wants to merge 1 commit into
TanStack:mainfrom
artemxknpv:codex/fix-query-options-declaration-emit
Open

fix query option declaration emit#10583
artemxknpv wants to merge 1 commit into
TanStack:mainfrom
artemxknpv:codex/fix-query-options-declaration-emit

Conversation

@artemxknpv
Copy link
Copy Markdown

@artemxknpv artemxknpv commented Apr 25, 2026

fixes #8453

This fixes TS4023 errors when a consumer exports an inferred queryOptions or infiniteQueryOptions value while emitting declarations.

The issue is that these helpers returned anonymous intersections like:

Options & { queryKey: DataTag<...> }

When TypeScript tried to emit a consumer .d.ts, it had to expand the tagged queryKey type and could end up referencing the internal dataTagSymbol / dataTagErrorSymbol unique symbols directly.

This patch keeps the same runtime behavior and the same tagged queryKey inference, but gives those return types exported names instead. That lets declaration emit reference the helper result type instead of expanding the internal tag fields.

The patch covers the adapters that had the same tagged return shape. Svelte only changes queryOptions, because its infiniteQueryOptions does not add a tagged queryKey return type.

I kept the committed regression tests small: they force declaration emit to name exported option values. I also verified the overload branches separately with a temporary consumer project that imports from package roots.

Verification:

  • consumer-style declaration emit repro using package root imports for all touched adapters
  • TypeScript 5.4, 5.5, 5.6, 5.7, 5.8, 5.9, 6.0 RC, and current
  • test:types:ts54 through test:types:ts60 for react, preact, vue, solid, angular experimental
  • test:types for svelte
  • test:eslint
  • prettier --check
  • git diff --check

Summary by CodeRabbit

  • Bug Fixes

    • Fixed TypeScript declaration emit for query option types across Angular, Preact, React, Solid, Svelte, and Vue query packages to prevent internal type symbols from appearing in generated consumer .d.ts files; introduced a helper type to stabilize emitted option typings.
  • Tests

    • Added regression tests to ensure declaration-emit/type-name inference remains stable for exported query option results.

Review Change Stack

@coderabbitai
Copy link
Copy Markdown
Contributor

coderabbitai Bot commented Apr 25, 2026

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info
⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: f9925e2f-e244-425e-bf1c-6034b93943eb

📥 Commits

Reviewing files that changed from the base of the PR and between b79d9c8 and a34a95c.

📒 Files selected for processing (24)
  • .changeset/fix-query-options-declaration-emit.md
  • packages/angular-query-experimental/src/__tests__/infinite-query-options.test-d.ts
  • packages/angular-query-experimental/src/__tests__/query-options.test-d.ts
  • packages/angular-query-experimental/src/infinite-query-options.ts
  • packages/angular-query-experimental/src/query-options.ts
  • packages/preact-query/src/__tests__/infiniteQueryOptions.test-d.tsx
  • packages/preact-query/src/__tests__/queryOptions.test-d.tsx
  • packages/preact-query/src/infiniteQueryOptions.ts
  • packages/preact-query/src/queryOptions.ts
  • packages/query-core/src/types.ts
  • packages/react-query/src/__tests__/infiniteQueryOptions.test-d.tsx
  • packages/react-query/src/__tests__/queryOptions.test-d.tsx
  • packages/react-query/src/infiniteQueryOptions.ts
  • packages/react-query/src/queryOptions.ts
  • packages/solid-query/src/__tests__/infiniteQueryOptions.test-d.tsx
  • packages/solid-query/src/__tests__/queryOptions.test-d.tsx
  • packages/solid-query/src/infiniteQueryOptions.ts
  • packages/solid-query/src/queryOptions.ts
  • packages/svelte-query/src/queryOptions.ts
  • packages/svelte-query/tests/queryOptions.test-d.ts
  • packages/vue-query/src/__tests__/infiniteQueryOptions.test-d.ts
  • packages/vue-query/src/__tests__/queryOptions.test-d.ts
  • packages/vue-query/src/infiniteQueryOptions.ts
  • packages/vue-query/src/queryOptions.ts
✅ Files skipped from review due to trivial changes (1)
  • .changeset/fix-query-options-declaration-emit.md
🚧 Files skipped from review as they are similar to previous changes (21)
  • packages/angular-query-experimental/src/tests/infinite-query-options.test-d.ts
  • packages/react-query/src/tests/queryOptions.test-d.tsx
  • packages/svelte-query/tests/queryOptions.test-d.ts
  • packages/vue-query/src/tests/queryOptions.test-d.ts
  • packages/solid-query/src/tests/queryOptions.test-d.tsx
  • packages/preact-query/src/tests/queryOptions.test-d.tsx
  • packages/angular-query-experimental/src/tests/query-options.test-d.ts
  • packages/react-query/src/tests/infiniteQueryOptions.test-d.tsx
  • packages/query-core/src/types.ts
  • packages/preact-query/src/tests/infiniteQueryOptions.test-d.tsx
  • packages/solid-query/src/tests/infiniteQueryOptions.test-d.tsx
  • packages/vue-query/src/infiniteQueryOptions.ts
  • packages/angular-query-experimental/src/query-options.ts
  • packages/vue-query/src/tests/infiniteQueryOptions.test-d.ts
  • packages/solid-query/src/infiniteQueryOptions.ts
  • packages/react-query/src/queryOptions.ts
  • packages/preact-query/src/queryOptions.ts
  • packages/solid-query/src/queryOptions.ts
  • packages/preact-query/src/infiniteQueryOptions.ts
  • packages/angular-query-experimental/src/infinite-query-options.ts
  • packages/svelte-query/src/queryOptions.ts

📝 Walkthrough

Walkthrough

Adds a QueryKeyWithDataTag type to query-core, replaces inline DataTag intersections with that named type in queryOptions/infiniteQueryOptions overloads across adapters, adds exported regression-test constants, and includes a changeset documenting the patch.

Changes

Query Options Declaration Emit Fix

Layer / File(s) Summary
Core QueryKeyWithDataTag type definition
packages/query-core/src/types.ts
Adds QueryKeyWithDataTag<TQueryKey, TQueryFnData, TError> to wrap a queryKey typed as DataTag<...>.
Angular query options refactor
packages/angular-query-experimental/src/query-options.ts, packages/angular-query-experimental/src/infinite-query-options.ts, packages/angular-query-experimental/src/__tests__/*
Replace inline { queryKey: DataTag<...> } intersections with QueryKeyWithDataTag<...> in overload return types and add exported regression-test constants.
Preact query options refactor
packages/preact-query/src/queryOptions.ts, packages/preact-query/src/infiniteQueryOptions.ts, packages/preact-query/src/__tests__/*
Update overload return types to use QueryKeyWithDataTag<...> and add exported regression-test constants.
React query options refactor
packages/react-query/src/queryOptions.ts, packages/react-query/src/infiniteQueryOptions.ts, packages/react-query/src/__tests__/*
Refactor overload return types to intersect with QueryKeyWithDataTag<...> and add exported regression-test constants to validate .d.ts emission.
Solid query options refactor
packages/solid-query/src/queryOptions.ts, packages/solid-query/src/infiniteQueryOptions.ts, packages/solid-query/src/__tests__/*
Replace inline DataTag intersections with QueryKeyWithDataTag<...> in overload return types and add exported regression-test constants.
Svelte query options refactor
packages/svelte-query/src/queryOptions.ts, packages/svelte-query/tests/*
Switch overload return types to QueryKeyWithDataTag<...> and add a regression-test export.
Vue query options refactor with type aliases
packages/vue-query/src/queryOptions.ts, packages/vue-query/src/infiniteQueryOptions.ts, packages/vue-query/src/__tests__/*
Introduce UndefinedInitialQueryOptionsWithDataTag / DefinedInitialQueryOptionsWithDataTag aliases and update overloads to return them; add exported regression-test constants.
Changeset patch documentation
.changeset/fix-query-options-declaration-emit.md
Adds a changeset documenting patch releases and that return types were fixed to emit cleanly into .d.ts files.

🎯 3 (Moderate) | ⏱️ ~25 minutes

Suggested Labels

package: query-core

Suggested Reviewers

  • TkDodo

Poem

🐇 In a thicket of types I nibbled a tag,
Found hidden symbols that made compilers gag.
With QueryKeyWithDataTag I knitted a seam,
Now exports are tidy and typings redeem—
Hooray, declaration files rest without lag!

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name Status Explanation Resolution
Docstring Coverage ⚠️ Warning Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%. Write docstrings for the functions missing them to satisfy the coverage threshold.
✅ Passed checks (4 passed)
Check name Status Explanation
Title check ✅ Passed The title 'fix query option declaration emit' directly describes the main change: fixing TypeScript declaration emit issues for queryOptions and infiniteQueryOptions.
Description check ✅ Passed The PR description thoroughly explains the issue, solution, verification steps, and affected adapters, though the provided template sections are mostly empty.
Linked Issues check ✅ Passed The PR directly addresses issue #8453 by refactoring return types to use exported QueryKeyWithDataTag helper, preventing TS4023 declaration emit errors when exporting queryOptions/infiniteQueryOptions results.
Out of Scope Changes check ✅ Passed All changes are within scope: refactoring return types across six TanStack query adapters, adding regression test exports, and creating the QueryKeyWithDataTag helper type.

✏️ Tip: You can configure your own custom pre-merge checks in the settings.

✨ Finishing Touches
🧪 Generate unit tests (beta)
  • Create PR with unit tests

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands and usage tips.

@artemxknpv
Copy link
Copy Markdown
Author

@TkDodo hi, quick check: is this worth a look?

it keeps runtime behavior the same and only names the helper return types so d.ts emit doesn't leak the internal DataTag symbols.

@artemxknpv
Copy link
Copy Markdown
Author

@TkDodo hi, sorry for another ping. is this still worth a review?

@nx-cloud
Copy link
Copy Markdown

nx-cloud Bot commented May 27, 2026

View your CI Pipeline Execution ↗ for commit f745f11

Command Status Duration Result
nx affected --targets=test:sherif,test:knip,tes... ✅ Succeeded 4m 6s View ↗
nx run-many --target=build --exclude=examples/*... ✅ Succeeded 1m 12s View ↗

☁️ Nx Cloud last updated this comment at 2026-05-27 14:13:41 UTC

@pkg-pr-new
Copy link
Copy Markdown

pkg-pr-new Bot commented May 27, 2026

More templates

@tanstack/angular-query-experimental

npm i https://pkg.pr.new/@tanstack/angular-query-experimental@10583

@tanstack/eslint-plugin-query

npm i https://pkg.pr.new/@tanstack/eslint-plugin-query@10583

@tanstack/lit-query

npm i https://pkg.pr.new/@tanstack/lit-query@10583

@tanstack/preact-query

npm i https://pkg.pr.new/@tanstack/preact-query@10583

@tanstack/preact-query-devtools

npm i https://pkg.pr.new/@tanstack/preact-query-devtools@10583

@tanstack/preact-query-persist-client

npm i https://pkg.pr.new/@tanstack/preact-query-persist-client@10583

@tanstack/query-async-storage-persister

npm i https://pkg.pr.new/@tanstack/query-async-storage-persister@10583

@tanstack/query-broadcast-client-experimental

npm i https://pkg.pr.new/@tanstack/query-broadcast-client-experimental@10583

@tanstack/query-core

npm i https://pkg.pr.new/@tanstack/query-core@10583

@tanstack/query-devtools

npm i https://pkg.pr.new/@tanstack/query-devtools@10583

@tanstack/query-persist-client-core

npm i https://pkg.pr.new/@tanstack/query-persist-client-core@10583

@tanstack/query-sync-storage-persister

npm i https://pkg.pr.new/@tanstack/query-sync-storage-persister@10583

@tanstack/react-query

npm i https://pkg.pr.new/@tanstack/react-query@10583

@tanstack/react-query-devtools

npm i https://pkg.pr.new/@tanstack/react-query-devtools@10583

@tanstack/react-query-next-experimental

npm i https://pkg.pr.new/@tanstack/react-query-next-experimental@10583

@tanstack/react-query-persist-client

npm i https://pkg.pr.new/@tanstack/react-query-persist-client@10583

@tanstack/solid-query

npm i https://pkg.pr.new/@tanstack/solid-query@10583

@tanstack/solid-query-devtools

npm i https://pkg.pr.new/@tanstack/solid-query-devtools@10583

@tanstack/solid-query-persist-client

npm i https://pkg.pr.new/@tanstack/solid-query-persist-client@10583

@tanstack/svelte-query

npm i https://pkg.pr.new/@tanstack/svelte-query@10583

@tanstack/svelte-query-devtools

npm i https://pkg.pr.new/@tanstack/svelte-query-devtools@10583

@tanstack/svelte-query-persist-client

npm i https://pkg.pr.new/@tanstack/svelte-query-persist-client@10583

@tanstack/vue-query

npm i https://pkg.pr.new/@tanstack/vue-query@10583

@tanstack/vue-query-devtools

npm i https://pkg.pr.new/@tanstack/vue-query-devtools@10583

commit: f745f11

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I tested this and the fix is fine in general, however, it seems to be enough for TypeScript to only name the DataTag itself:

type QueryKeyWithDataTag<
  TQueryKey extends QueryKey = QueryKey,
  TQueryFnData = unknown,
  TError = DefaultError,
> = {
  queryKey: DataTag<TQueryKey, TQueryFnData, TError>
}

which we don’t need to export and we can add to all return types instead of the inline type:

-): DefinedInitialDataOptions<TQueryFnData, TError, TData, TQueryKey> & {
-  queryKey: DataTag<TQueryKey, TQueryFnData, TError>
-}
+): DefinedInitialDataOptions<TQueryFnData, TError, TData, TQueryKey> &
+  QueryKeyWithDataTag<TQueryKey, TQueryFnData, TError>

would be good if we could use this approach please. Might even be enough to have this type QueryKeyWithDataTag once in the query core.

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

updated in a34a95c. moved QueryKeyWithDataTag to query-core and switched the overload returns to use it.

Vue still needs local named aliases in queryOptions.ts for declaration emit, but they are not re-exported from the package entry.

@artemxknpv artemxknpv force-pushed the codex/fix-query-options-declaration-emit branch 2 times, most recently from 9cf638a to b79d9c8 Compare May 27, 2026 16:54
Copy link
Copy Markdown
Contributor

@coderabbitai coderabbitai Bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@packages/solid-query/src/infiniteQueryOptions.ts`:
- Around line 61-62: The overloads of infiniteQueryOptions are using
QueryKeyWithDataTag<TQueryKey, InfiniteData<TQueryFnData>> and thus drop the
user-specified TError (it falls back to DefaultError); update both overload
signatures to propagate TError into the tagged key by changing the type to
QueryKeyWithDataTag<TQueryKey, InfiniteData<TQueryFnData>, TError> so the tagged
QueryKey retains the correct error type (modify the two overload signatures in
infiniteQueryOptions that reference QueryKeyWithDataTag accordingly).
🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

  • Push a commit to this branch (recommended)
  • Create a new PR with the fixes

ℹ️ Review info
⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 3f13d8e2-a392-439f-b4aa-e30ece70f3e2

📥 Commits

Reviewing files that changed from the base of the PR and between 9cf638a and b79d9c8.

📒 Files selected for processing (24)
  • .changeset/fix-query-options-declaration-emit.md
  • packages/angular-query-experimental/src/__tests__/infinite-query-options.test-d.ts
  • packages/angular-query-experimental/src/__tests__/query-options.test-d.ts
  • packages/angular-query-experimental/src/infinite-query-options.ts
  • packages/angular-query-experimental/src/query-options.ts
  • packages/preact-query/src/__tests__/infiniteQueryOptions.test-d.tsx
  • packages/preact-query/src/__tests__/queryOptions.test-d.tsx
  • packages/preact-query/src/infiniteQueryOptions.ts
  • packages/preact-query/src/queryOptions.ts
  • packages/query-core/src/types.ts
  • packages/react-query/src/__tests__/infiniteQueryOptions.test-d.tsx
  • packages/react-query/src/__tests__/queryOptions.test-d.tsx
  • packages/react-query/src/infiniteQueryOptions.ts
  • packages/react-query/src/queryOptions.ts
  • packages/solid-query/src/__tests__/infiniteQueryOptions.test-d.tsx
  • packages/solid-query/src/__tests__/queryOptions.test-d.tsx
  • packages/solid-query/src/infiniteQueryOptions.ts
  • packages/solid-query/src/queryOptions.ts
  • packages/svelte-query/src/queryOptions.ts
  • packages/svelte-query/tests/queryOptions.test-d.ts
  • packages/vue-query/src/__tests__/infiniteQueryOptions.test-d.ts
  • packages/vue-query/src/__tests__/queryOptions.test-d.ts
  • packages/vue-query/src/infiniteQueryOptions.ts
  • packages/vue-query/src/queryOptions.ts
✅ Files skipped from review due to trivial changes (1)
  • .changeset/fix-query-options-declaration-emit.md
🚧 Files skipped from review as they are similar to previous changes (11)
  • packages/angular-query-experimental/src/tests/infinite-query-options.test-d.ts
  • packages/react-query/src/tests/infiniteQueryOptions.test-d.tsx
  • packages/vue-query/src/tests/infiniteQueryOptions.test-d.ts
  • packages/solid-query/src/tests/infiniteQueryOptions.test-d.tsx
  • packages/react-query/src/tests/queryOptions.test-d.tsx
  • packages/svelte-query/tests/queryOptions.test-d.ts
  • packages/vue-query/src/tests/queryOptions.test-d.ts
  • packages/preact-query/src/tests/infiniteQueryOptions.test-d.tsx
  • packages/preact-query/src/tests/queryOptions.test-d.tsx
  • packages/angular-query-experimental/src/tests/query-options.test-d.ts
  • packages/angular-query-experimental/src/query-options.ts

Comment thread packages/solid-query/src/infiniteQueryOptions.ts Outdated
@artemxknpv artemxknpv force-pushed the codex/fix-query-options-declaration-emit branch from b79d9c8 to a34a95c Compare May 27, 2026 17:04
@artemxknpv artemxknpv requested a review from TkDodo May 27, 2026 17:16
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

TypeScript errors when using exported queryOptions factory in @tanstack/react-query 5.62.8

2 participants