docs({react,preact}-query): correct 'initialData'/'select' and 'QueriesOptions' fallback JSDoc inaccuracies by sukvvon · Pull Request #11574 · TanStack/query

sukvvon · 2026-09-22T05:53:16Z

🎯 Changes

Two JSDoc inaccuracies in @tanstack/react-query and @tanstack/preact-query (identical source structure in both packages):

DefinedInitialDataOptions, DefinedInitialDataInfiniteOptions, DefinedUseQueryResult, DefinedUseInfiniteQueryResult, and the two useQuery/queryOptions overloads selected when initialData is set all stated that data is "never undefined" without qualification. This is only true when no select is used — a select can change TData to a type that includes undefined. Added the (unless a select changes TData to include undefined) qualifier, consistent with the existing @template TData doc on these types.
QueriesOptions and SuspenseQueriesOptions (the queries array type for useQueries/useSuspenseQueries) stated that only "a non-tuple array of a known element type, or a tuple past 20 elements" falls back to a single homogeneous options type. This conflated two different cases: a non-tuple array whose element type structurally matches a query options object is mapped per-element (not a fallback), while any other non-tuple array — one whose element type doesn't match the expected shape — does fall back, independent of the 20-element tuple limit. Reworded to separate these cases correctly, and split the QueriesOptions/SuspenseQueriesOptions doc comments into paragraphs for readability.

✅ Checklist

I have followed the steps in the Contributing guide.
I have tested code changes locally with pnpm run test:pr, or these tests do not apply to this pull request.
I fully understand the code in this pull request, including any code generated with AI assistance.

🚀 Release Impact

This change affects published code, and I have generated a changeset.
This change is docs/CI/dev-only (no release).

Summary by CodeRabbit

Documentation
- Updated React and Preact reference links to point to current source locations.
- Clarified when query data may be undefined after a select transformation, including cases with initial data.
- Refined documentation for query and suspense-query array inference, tuple limits, and fallback behavior.
- Improved explanations for mutation and query result types.
- No functional, API, or type-signature changes were made.

coderabbitai · 2026-09-22T05:53:35Z

Navigate logical layers of code changes, visualize relationships, and explore their blast radius.

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository: TanStack/query/.coderabbit.yaml

Review profile: CHILL

Plan: Advanced

Run ID: 5dc192ff-6eb5-4a0d-b190-f57346f2ac33

📥 Commits

Reviewing files that changed from the base of the PR and between d5a764d and e84f699.

📒 Files selected for processing (4)

docs/framework/preact/reference/type-aliases/DefinedInitialDataOptions.md
docs/framework/react/reference/type-aliases/DefinedInitialDataOptions.md
packages/preact-query/src/queryOptions.ts
packages/react-query/src/queryOptions.ts

🚧 Files skipped from review as they are similar to previous changes (2)

packages/preact-query/src/queryOptions.ts
packages/react-query/src/queryOptions.ts

Included review availability: Your plan provides up to 10 included reviews per hour; 7 remain after this review.

📝 Walkthrough

Walkthrough

The pull request updates React and Preact Query JSDoc and reference documentation. It clarifies select effects on defined data, documents array inference cases, and refreshes generated source line links. No code behavior or public declarations changed.

Changes

Query documentation updates

Layer / File(s)	Summary
Defined data guarantees `packages/{react,preact}-query/src/{queryOptions.ts,useQuery.ts,infiniteQueryOptions.ts,types.ts}`, `docs/framework/{react,preact}/reference/{functions,type-aliases}/*`	Documentation now states that `select` can make `data` include `undefined` on otherwise defined-data options and result types.
Array inference documentation `packages/{react,preact}-query/src/{useQueries.ts,useSuspenseQueries.ts}`, `docs/framework/{react,preact}/reference/type-aliases/{QueriesOptions,SuspenseQueriesOptions}.md`	Documentation distinguishes tuple limits, opaque arrays, per-element mapping for matching non-tuple arrays, and homogeneous fallback cases.
React source-link alignment `docs/framework/react/reference/{functions,interfaces,type-aliases}/*`	React reference links now point to updated source line numbers.
Preact source-link alignment `docs/framework/preact/reference/{functions,interfaces,type-aliases}/*`	Preact reference links now point to updated source line numbers.

Priority: ⬇️ Low

Estimated code review effort: 1 (Trivial) | ~5 minutes

Change: Other

Possibly related PRs

TanStack/query#11204: Added the Preact JSDoc that this pull request corrects.
TanStack/query#11284: Added documentation for the query option, result, and array inference contracts updated here.

Suggested reviewers: tkdodo

Merge Risk: ⚪ Minimal · up to e84f6

This update clarifies existing Query documentation and source links without changing runtime behavior or the public API, so it is ready to merge.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff. Analyzed 0 functions across 1…
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Title check	✅ Passed	The title clearly summarizes the documentation changes. It identifies the corrected initialData/select behavior and QueriesOptions fallback JSDoc inaccuracies across React and Preact Query.
Description check	✅ Passed	The description includes all required template sections. It explains the changes and motivation, completes the checklist, and correctly identifies the change as documentation-only with no release impa…

✨ Finishing Touches

📝 Generate docstrings

Commit to this branch
Create a new PR

🧪 Generate unit tests (beta)

Commit to this branch
Create a new PR

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.}

nx-cloud · 2026-09-22T05:53:44Z

View your CI Pipeline Execution ↗ for commit e84f699

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

☁️ Nx Cloud last updated this comment at 2026-09-22 06:36:55 UTC

github-actions · 2026-09-22T05:54:19Z

🚀 Changeset Version Preview

No changeset entries found. Merging this PR will not cause a version bump for any packages.

…into paragraphs

pkg-pr-new · 2026-09-22T05:57:34Z

More templates

@tanstack/angular-query-experimental

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

@tanstack/eslint-plugin-query

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

@tanstack/lit-query

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

@tanstack/preact-query

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

@tanstack/preact-query-devtools

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

@tanstack/preact-query-persist-client

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

@tanstack/query-async-storage-persister

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

@tanstack/query-broadcast-client-experimental

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

@tanstack/query-core

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

@tanstack/query-devtools

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

@tanstack/query-persist-client-core

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

@tanstack/query-sync-storage-persister

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

@tanstack/react-query

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

@tanstack/react-query-devtools

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

@tanstack/react-query-next-experimental

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

@tanstack/react-query-persist-client

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

@tanstack/solid-query

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

@tanstack/solid-query-devtools

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

@tanstack/solid-query-persist-client

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

@tanstack/svelte-query

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

@tanstack/svelte-query-devtools

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

@tanstack/svelte-query-persist-client

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

@tanstack/vue-query

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

@tanstack/vue-query-devtools

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

commit: e84f699

github-actions · 2026-09-22T05:57:55Z

size-limit report 📦

Path	Size
react full	11.87 KB (0%)
react minimal	8.85 KB (0%)

…s' fallback JSDoc inaccuracies

…InitialDataOptions' JSDoc

docs(react-query): correct inaccurate JSDoc statements

1265268

sukvvon self-assigned this Sep 22, 2026

docs(react-query): split QueriesOptions/SuspenseQueriesOptions JSDoc …

7cfc724

…into paragraphs

sukvvon changed the title ~~docs(react-query): correct inaccurate JSDoc statements~~ docs(react-query): correct 'initialData'/'select' and 'QueriesOptions' fallback JSDoc inaccuracies Sep 22, 2026

docs(preact-query): correct 'initialData'/'select' and 'QueriesOption…

d5a764d

…s' fallback JSDoc inaccuracies

sukvvon changed the title ~~docs(react-query): correct 'initialData'/'select' and 'QueriesOptions' fallback JSDoc inaccuracies~~ docs({react,preact}-query): correct 'initialData'/'select' and 'QueriesOptions' fallback JSDoc inaccuracies Sep 22, 2026

sukvvon mentioned this pull request Sep 22, 2026

docs(vue-query): correct 'initialData'/'select' JSDoc inaccuracy #11575

Open

5 tasks

docs({react,preact}-query): fix missed 'select' qualifier on 'Defined…

e84f699

…InitialDataOptions' JSDoc

This was referenced Sep 22, 2026

docs(solid-query): correct 'initialData'/'select' JSDoc inaccuracy #11576

Open

docs(svelte-query): correct 'initialData'/'select' JSDoc inaccuracy #11577

Open

Navigation Menu

Uh oh!

docs({react,preact}-query): correct 'initialData'/'select' and 'QueriesOptions' fallback JSDoc inaccuracies - #11574

docs({react,preact}-query): correct 'initialData'/'select' and 'QueriesOptions' fallback JSDoc inaccuracies#11574
sukvvon wants to merge 4 commits into
mainfrom
docs/react-query-jsdoc-inaccuracy-fixes

sukvvon commented Sep 22, 2026 •

edited by coderabbitai Bot

Loading

Uh oh!

coderabbitai Bot commented Sep 22, 2026 •

edited

Loading

Walkthrough

Changes

Uh oh!

nx-cloud Bot commented Sep 22, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Sep 22, 2026

Uh oh!

pkg-pr-new Bot commented Sep 22, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Sep 22, 2026

Uh oh!

This branch has not been deployed

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Uh oh!

Conversation

sukvvon commented Sep 22, 2026 • edited by coderabbitai Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🎯 Changes

✅ Checklist

🚀 Release Impact

Summary by CodeRabbit

Uh oh!

coderabbitai Bot commented Sep 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Walkthrough

Changes

Uh oh!

nx-cloud Bot commented Sep 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions Bot commented Sep 22, 2026

🚀 Changeset Version Preview

Uh oh!

pkg-pr-new Bot commented Sep 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions Bot commented Sep 22, 2026

size-limit report 📦

Uh oh!

This branch has not been deployed

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

sukvvon commented Sep 22, 2026 •

edited by coderabbitai Bot

Loading

coderabbitai Bot commented Sep 22, 2026 •

edited

Loading

nx-cloud Bot commented Sep 22, 2026 •

edited

Loading

pkg-pr-new Bot commented Sep 22, 2026 •

edited

Loading