docs(query-core): add JSDoc across the package and expose it in generated reference docs - #11438
Open
sukvvon wants to merge 9 commits into
Open
docs(query-core): add JSDoc across the package and expose it in generated reference docs#11438sukvvon wants to merge 9 commits into
sukvvon wants to merge 9 commits into
Conversation
…ated reference docs
Contributor
|
Important Review skippedToo many files! This PR contains 1443 files, which is 1143 over the limit of 300. To get a review, reduce the PR to 300 files or fewer by splitting it into smaller PRs or changing its base branch. Usage-priced reviews support at most 300 files. ⚙️ Run configurationConfiguration used: Path: .coderabbit.yaml Review profile: CHILL Plan: Team Run ID: 📒 Files selected for processing (1443)
You can disable this status message by setting the |
|
View your CI Pipeline Execution ↗ for commit 077deb8
☁️ Nx Cloud last updated this comment at |
Contributor
🚀 Changeset Version Preview2 package(s) bumped directly, 23 bumped as dependents. 🟨 Minor bumps
🟩 Patch bumps
|
Contributor
size-limit report 📦
|
…ence' pages into JSDoc
…the generated reference
sukvvon
marked this pull request as ready for review
September 6, 2026 18:46
sukvvon
marked this pull request as draft
September 6, 2026 19:14
Member
Author
|
A few non-obvious spots worth a closer look, since this diff is large (pinned to current HEAD,
Update: #11371 (old reference URLs falling through to the docs homepage instead of redirecting) is fixed by Note for anyone mid-review: the latest commit ( |
sukvvon
marked this pull request as ready for review
September 6, 2026 20:06
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
🎯 Changes
query-core's public API (options likestaleTime/gcTime, and classes likeQueryClient,Query,QueryObserver, ...) previously had little to no JSDoc. On top of that, every adapter's TypeDoc config (scripts/generate-docs.ts) explicitly excludedquery-corefrom reference-doc generation viaexclude: ['./packages/query-core/**/*']. Together, this meant generated reference docs for framework-level hooks/functions (e.g.useQuery'soptionsparameter) couldn't render the underlyingquery-core-derived property details — see #11371 and Discussion #11404, where users reported not being able to tell what options exist just from the generated reference.Rather than creating a separate "Core reference" doc hub, this PR documents
query-corein place and lets each adapter's existing generated reference pull those docs in automatically, since every adapter's options types are ultimately derived fromquery-core.1. JSDoc added across
packages/query-core/src18 of the 20
packages/query-core/src/*.tsfiles touched by this PR, ~1700 lines of JSDoc added (environmentManager.tsandindex.tsare the other 2, covered in sections 7 and 8 below):types.tsQueryOptions(retry,retryDelay,networkMode,queryFn,persister,queryHash,queryKey,queryKeyHashFn,initialData,initialDataUpdatedAt) andQueryObserverOptions(staleTime,gcTime,refetchOnMount,refetchOnWindowFocus,refetchOnReconnect,select)queryClient.tsQueryClientclass +query,infiniteQuery,fetchQuery/fetchInfiniteQuery(deprecated, superseded byquery/infiniteQuery),getQueriesData,setQueryData,setQueriesData,getQueryState,removeQueries,resetQueries,cancelQueries,invalidateQueries,refetchQueries,resumePausedMutations,getQueryCache,getMutationCache,get/setDefaultOptions,get/setQueryDefaults,get/setMutationDefaults,clear,isFetching,isMutating,mount,unmount,defaultQueryOptions,defaultMutationOptionsqueryCache.tsQueryCacheclass,QueryCacheConfig,QueryCacheNotifyEvent,build,remove,get,find,findAll,clear,getAllmutationCache.tsMutationCacheclass,MutationCacheConfig,MutationCacheNotifyEvent,getAll,clear,find,findAllquery.tsQueryState,Queryclass,meta/promisegetters,cancel,destroy,reset,isActive,isDisabled,isFetched,isStatic,isStale,isStaleByTime,invalidate,fetch,getObserversCount,setStatequeryObserver.tsQueryObserverclass,setOptions,getCurrentResult,getCurrentQuery,refetch,fetchOptimistic,destroy,shouldFetchOnReconnect,shouldFetchOnWindowFocus,getOptimisticResult,trackResult,trackProp,updateResultqueriesObserver.tsQueriesObserverclass,QueriesObserverOptions,destroy,setQueries,getCurrentResult,getQueries,getObservers,getOptimisticResultinfiniteQueryObserver.tsInfiniteQueryObserverclass,setOptions,fetchNextPage,fetchPreviousPage,getOptimisticResultmutation.tsMutationState,Mutationclass,metagetter,continue,executemutationObserver.tsMutationObserverclass,mutate,getCurrentResult,reset,setOptionsfocusManager.ts,onlineManager.ts,timeoutManager.ts,notifyManager.ts,utils.ts,hydration.ts,retryer.ts,streamedQuery.tsdocs/reference/*.mdand current source behaviorDescriptions were written against, and in a few cases corrected relative to, the legacy
docs/reference/*.mdprose where it no longer matched current code — e.g.staleTime: 'static'does not disablerefetchInterval(only stops staleness-based refetches),cancelQueriesresolvesPromise<void>withrevert: trueas the default, andsetQueryData's updater short-circuits when it returnsundefined.58
@exampleblocks and 16@seecross-references (e.g.getQueryDefaults↔setQueryDefaults,isStale↔isStaleByTime) were added on top of the prose.2.
@internaltagging29 members with no caller outside
query-coreare tagged@internal, which excludes them from generated docs (their.d.tsoutput and runtime behavior are unaffected —@internalis TypeDoc-only). Tagging was done by auditing actual external call sites in the monorepo (all 7 framework adapters,query-broadcast-client-experimental,query-persist-client-core,query-devtools) rather than by guessing from the method's name — several methods that look internal by naming convention are in fact called directly by adapters or plugins and are documented instead, e.g.:QueryClient.mount/unmount— called by every adapter'sQueryClientProvider-equivalentQuery.setState— called byquery-broadcast-client-experimental,query-persist-client-core, devtoolsQueryCache.build/get— called by plugins that need to get-or-create aQuerydirectlyQueryObserver.getOptimisticResult/trackResult/trackProp/updateResult— called by every adapter'suseBaseQuery-equivalentQueriesObserver.getOptimisticResult,InfiniteQueryObserver.getOptimisticResult— called byuseQueries/infinite-query adapter code3.
scripts/generate-docs.ts: removequery-coreexclusionRemoved
exclude: ['./packages/query-core/**/*']from all 7 adapter configs (angular-query-experimental,svelte-query,solid-query,vue-query,react-query,preact-query,lit-query), soquery-coresymbols referenced by adapter option types (e.g.staleTimeonUseQueryOptions) now render inline instead of being excluded.query-core-derived symbols (e.g.QueryClient,focusManager) are now duplicated across each adapter's generated reference — this is intentional per-adapter self-containment, matching howquery-coretypes were already inlined/duplicated for adapters that didn't have the exclude misconfigured.Also fixes
generatePackageReferenceDocspassingexclude: pkg.excludeverbatim to TypeDoc, which broke whenpkg.excludewasundefined("The 'exclude' option must be set to an array of strings"); changed to...(pkg.exclude && { exclude: pkg.exclude }).4. tsconfig: drop
query-coreproject referenceRemoved the
query-coreTypeScript project reference fromangular-query-experimental,svelte-query,solid-query,vue-query, andlit-query'stsconfig.json. With the reference in place, TypeDoc/tsc resolvedquery-coretypes through itsdist-tsbuild output rather than its.tssource, which meant generated docs couldn't produce GitHub source links forquery-coresymbols (they rendered as plain text instead of linked, e.g.useInfiniteQuery.ts:70-style links).angular-query-experimentalkeeps itsquery-devtoolsreference (needed for JSX/TSX compilation), which was initially assumed to reintroduce the samedist-tsresolution for angular'squery-corepages — butquery-devtools's owntsconfig.jsoncarried an unnecessaryquery-corereference of its own (transitively routing angular → query-devtools → query-core throughdist-ts). Removed that reference too, so all 7 frameworks now consistently produce linked.tssource paths forquery-coresymbols.This does not affect build output or dependency ordering: nx's project graph is derived from each package's actual
package.jsondependencies(e.g."@tanstack/query-core": "workspace:*"), not fromtsconfig.jsonreferences. Verified withnx run-many --target=compile,test:types,test:eslint,build,test:lib --projects=vue-query,angular-query-experimental,svelte-query,solid-query,lit-query,query-devtools,angular-query-persist-client --skip-nx-cacheagainst a cleandist-ts, all green.5. Regenerated docs
Ran
pnpm run generate-docsto regenerate all reference docs underdocs/framework/*/reference/reflecting the above (net ~1150 files touched, mostly newquery-core-derived pages plus updated cross-links/source-line numbers in existing adapter pages).6.
docs/config.json: add sidebar entries for the newly generated pagesEach framework's TypeDoc-generated reference pages are also manually listed in
docs/config.jsonto appear in the docs site sidebar. Added an entry for every newly generatedquery-core-derived page (classes, functions, interfaces, types, variables) under each framework's existingAPI Referencesection, grouped and alphabetized consistently with each framework's existing category convention (Functions/Classes/Interfaces/Types/Variables), without disturbing pre-existing entries or lit's specialContextgrouping.7. Migrate remaining prose from
docs/reference/*.mdinto JSDocdocs/reference/*.md(12 files:QueryClient,QueryCache,MutationCache,QueryObserver,InfiniteQueryObserver,QueriesObserver,focusManager,onlineManager,notifyManager,timeoutManager,environmentManager,streamedQuery) are legacy hand-written pages that predate TypeDoc and are not generated — see section 6 in this PR's changes for why they still exist and aren't removed here. Comparing their content against the JSDoc from section 1 turned up a few gaps, filled in this batch:QueryClient.query()'s excluded-option list is now derived from the type relationship (QueryExecuteOptions extends QueryOptions, whereasQueryObserverOptions extends QueryOptionsadds the reactive-only fields) rather than copied from the legacy doc's list — which, on inspection, was missingretryOnMountand pinned to a 2-year-old commit permalink.InvalidateQueryFilters.refetchType's four values (active/inactive/all/none) andResultOptions.throwOnErrornow have JSDoc; both were previously undocumented intypes.ts.QueryClientConfigandDefaultOptionsfields now have JSDoc.QueryClient.getQueriesData()now documents why itsTQueryFnDatageneric defaults tounknown(matched queries can hold different shapes; a more specific type is an unchecked convenience, not inferred).QueryCacheConfignow notes its callbacks are fire-and-forget, unlikeMutationCacheConfig's (verified againstquery.ts:QueryCache'sonSuccess/onError/onSettledcalls aren't awaited,MutationCache's are).QueryCache/MutationCachenow have an@exampleforsubscribe(inherited fromSubscribable, which isn't itself exported, so it can't carry its own JSDoc/page).TimeoutProvidernow documents the short-lived-vs-coalesced timer tradeoff that motivates a custom provider.notifyManager.setBatchNotifyFunctionnow has a framework-neutral description (dropped a stray "React Query" reference from this framework-agnostic package) and the solid-querybatchintegration example from the legacy doc.environmentManagernow documents its override/restore use case with a corrected example (the legacy doc'ssetIsServer(() => isServer)referred to the booleanisServerexport fromutils.ts, not the differently-named function inenvironmentManager.ts— using the latter's shape here would have set up infinite recursion).streamedQuery's@param queryFnwas renamed to@param streamFnto match the actual parameter name, and its options object types now carry field-level JSDoc too (though TypeDoc doesn't currently render those on this destructured-parameter signature — a pre-existing TypeDoc limitation, not something this PR fixes).Not migrated, and not planned to be: relative doc links (
../framework/react/guides/...),redirect_fromfrontmatter, the commit-pinned source permalink, the TkDodo "Inside React Query" blog link, and mentions of adapter-specific hooks (useIsFetching,useIsMutating) or "options are the same asuseQuery" — none of these translate into a framework-neutral package whose JSDoc is rendered into seven different framework trees.8. Delete
docs/reference/*.md, now that its content has been migratedWith the prose from section 7 migrated into JSDoc, all 12 legacy
docs/reference/*.mdpages (QueryClient,QueryCache,MutationCache,QueryObserver,InfiniteQueryObserver,QueriesObserver,focusManager,onlineManager,notifyManager,timeoutManager,environmentManager,streamedQuery) are deleted, along with the framework-agnosticAPI Referencechildrenindocs/config.jsonthat linked to them.redirect_fromfrontmatter (pointing at oldframework/react/reference/<Name>URLs) had those redirects re-registered, viagenerate-docs.ts's existingredirectFrommechanism, onto the new generated page that carries the equivalent content — plus the bare/reference/<Name>URL from the old sidebar for all 12 pages (streamedQuery,environmentManager, andtimeoutManagerdidn't have aredirect_frombefore, since they were added after the flat-URL era, but did have a/reference/<Name>sidebar URL). Docs deleted #11371 tracked these old URLs falling through to the docs homepage instead of redirecting;TanStack/tanstack.com#1217(merged) fixed the underlying cause — a GitHub webhook 10s timeout was cutting off cache invalidation/CDN purge beforeredirect_fromchanges could take effect — and I verified in-browser that already-live equivalents (e.g.docs/framework/react/reference/useQuery→.../functions/useQuery) now redirect correctly. Only react ever had these legacy pages/URLs; the other 6 frameworks are unaffected.#queryclientclear→#clear), verified against the equivalent already-live generated page on tanstack.com.focusManager,onlineManager, andtimeoutManagerare exported as instances of theFocusManager/OnlineManager/TimeoutManagerclasses, and those classes weren't themselves exported fromquery-core's entry point — so TypeDoc could only render a 3-line stub for the instance (no method docs), which would have silently dropped thesetEventListener/setFocused/isFocused-style documentation the legacy pages carried. Fixed by addingexport type { FocusManager, OnlineManager, TimeoutManager }toquery-core'sindex.ts(type-only, no runtime change, but new published surface — see the changeset). TypeDoc now generates a fullinterfaces/<Name>.mdpage for each with all methods and examples, and the redirects above point there instead of at the stub.environmentManagerandnotifyManagerdidn't need this — both are plain object literals, so TypeDoc already inlines their methods on the instance's own page.This closes out the
docs/referencelegacy-doc-removal work: options/API descriptions forquery-corenow live solely in JSDoc, surfaced through each framework's generated reference.9. Fix
query-devtools's own unnecessaryquery-coreproject referenceFound while investigating why
angular-query-experimental(the one framework whose docs still resolved throughdist-tsafter section 4) hadn't been fixed by the exclusion changes above:packages/query-devtools/tsconfig.jsoncarried its ownquery-coreproject reference thatangular-query-experimentaltransitively pulled in via its (required, JSX-compilation-only)query-devtoolsreference. Removed it — same@tanstack/custom-conditionreasoning as section 4 — so all 7 frameworks now consistently resolvequery-coresymbols through.tssource. Verifiednx run-many --target=compile,test:types,test:eslint,build,test:lib --projects=preact-query-devtools,react-query-devtools,solid-query-devtools,svelte-query-devtools,vue-query-devtools --skip-nx-cacheagainst a cleandist-ts, all green.10. Document previously-missing default values, and normalize "Defaults to" spacing
A pass over
types.ts(andqueriesObserver.ts/utils.ts) looking for options that already had a description but no stated default, or that had one immediately abutting the description with no line break (inconsistent with most of the file):QueryOptions/MutationOptions:retryDelay(defaults to exponential backoff capped at 30s — was previously only described via example, no stated default),networkMode(added a describing sentence; it previously jumped straight to "Defaults to'online'" with none)MutationOptions.retry/networkMode/gcTime: same "Defaults to ..." treatment as theirQueryOptionscounterparts, but the actual defaults differ and weren't copy-pasted — mutationretrydefaults to0vs. query's client/server3/0split (retryer.tsvs.mutation.ts);networkMode/gcTimematchQueryOptionsQueriesObserverOptions.combine: defaults to returning the raw per-query result array unchangedQueryFilters.type: defaults to'all'(confirmed via thetype = 'all'destructure inutils.ts)MutationObserverOptions.throwOnError: had no JSDoc at all, unlikeQueryObserverOptions.throwOnError's full description — added, defaultfalseconfirmed viashouldThrowError's!!throwOnErrorfallbacknotifyOnChangeProps: reworded its prose-only default explanation into the same "Defaults to ..." shape as its thirteen sibling fieldsNo behavior changes; this is documentation-only. Verified with
pnpm run generate-docsthat only the intended sentences render as new content, with no deleted descriptions.✅ Checklist
pnpm run test:pr, or these tests do not apply to this pull request.🚀 Release Impact
@tanstack/query-coreminor, for theFocusManager/OnlineManager/TimeoutManagertype exports in section 8 — everything else in this PR is docs-only).