# Behavior traces — TanStack/query

> Canonical page: https://codevetter.com/unpack/query/behavior-traces

# Behavior traces — TanStack/query

Scanned commit 29859ae60c8dca0a5cdbf8abccc775b655cf43e2 (2026-10-02). Generated by codevetter codevetter 1.15.0 on 2026-10-02.

Source inspection; upstream code and tests were not executed.

The investigation followed startup, primary fetch, optimistic mutation, and persistent restoration through concrete source files. These are source execution traces rather than observed runtime recordings. Each trace retains important conditional branches, including stale-cache reuse, restoration gating, cancellation, and scope queues. The offline example supplies an application-level path connecting these library mechanisms.
- Offline example startup calls worker.start, resolves #root, and renders App; App supplies its configured client and localStorage persister to PersistQueryClientProvider. — [examples/react/offline/src/index.tsx#L1-L14](https://github.com/TanStack/query/blob/29859ae60c8dca0a5cdbf8abccc775b655cf43e2/examples/react/offline/src/index.tsx#L1-L14) [examples/react/offline/src/App.tsx#L24-L47](https://github.com/TanStack/query/blob/29859ae60c8dca0a5cdbf8abccc775b655cf43e2/examples/react/offline/src/App.tsx#L24-L47) [examples/react/offline/src/App.tsx#L58-L73](https://github.com/TanStack/query/blob/29859ae60c8dca0a5cdbf8abccc775b655cf43e2/examples/react/offline/src/App.tsx#L58-L73)
- Provider lifecycle runs QueryClientProvider's effect → client.mount → focusManager/onlineManager subscriptions; positive events await resumePausedMutations before notifying the query cache, and the last unmount removes subscriptions. — [packages/react-query/src/QueryClientProvider.tsx#L70-L85](https://github.com/TanStack/query/blob/29859ae60c8dca0a5cdbf8abccc775b655cf43e2/packages/react-query/src/QueryClientProvider.tsx#L70-L85) [packages/query-core/src/queryClient.ts#L104-L135](https://github.com/TanStack/query/blob/29859ae60c8dca0a5cdbf8abccc775b655cf43e2/packages/query-core/src/queryClient.ts#L104-L135)
- React query flow runs useQuery → useBaseQuery → useQueryClient/defaultQueryOptions → new QueryObserver → getOptimisticResult → useSyncExternalStore subscription; restoring or subscribed:false prevents that subscription. — [packages/react-query/src/useQuery.ts#L296-L298](https://github.com/TanStack/query/blob/29859ae60c8dca0a5cdbf8abccc775b655cf43e2/packages/react-query/src/useQuery.ts#L296-L298) [packages/react-query/src/useBaseQuery.ts#L51-L89](https://github.com/TanStack/query/blob/29859ae60c8dca0a5cdbf8abccc775b655cf43e2/packages/react-query/src/useBaseQuery.ts#L51-L89) [packages/react-query/src/useBaseQuery.ts#L91-L116](https://github.com/TanStack/query/blob/29859ae60c8dca0a5cdbf8abccc775b655cf43e2/packages/react-query/src/useBaseQuery.ts#L91-L116)
- The first observer subscriber runs addObserver → shouldFetchOnMount → executeFetch → Query.fetch → retryer.start → queryFn; success calls setData → dispatch → observer.onQueryUpdate → updateResult and framework notification. — [packages/query-core/src/queryObserver.ts#L110-L121](https://github.com/TanStack/query/blob/29859ae60c8dca0a5cdbf8abccc775b655cf43e2/packages/query-core/src/queryObserver.ts#L110-L121) [packages/query-core/src/queryObserver.ts#L459-L475](https://github.com/TanStack/query/blob/29859ae60c8dca0a5cdbf8abccc775b655cf43e2/packages/query-core/src/queryObserver.ts#L459-L475) [packages/query-core/src/query.ts#L725-L775](https://github.com/TanStack/query/blob/29859ae60c8dca0a5cdbf8abccc775b655cf43e2/packages/query-core/src/query.ts#L725-L775) [packages/query-core/src/query.ts#L892-L902](https://github.com/TanStack/query/blob/29859ae60c8dca0a5cdbf8abccc775b655cf43e2/packages/query-core/src/query.ts#L892-L902)
- Imperative fetch runs queryClient.query → defaultQueryOptions → QueryCache.build → isStaleByTime; stale entries fetch and fresh entries reuse state.data, with retries disabled unless explicitly configured and select applied afterward. — [packages/query-core/src/queryClient.ts#L580-L604](https://github.com/TanStack/query/blob/29859ae60c8dca0a5cdbf8abccc775b655cf43e2/packages/query-core/src/queryClient.ts#L580-L604) [packages/query-core/src/queryCache.ts#L159-L177](https://github.com/TanStack/query/blob/29859ae60c8dca0a5cdbf8abccc775b655cf43e2/packages/query-core/src/queryCache.ts#L159-L177) [packages/query-core/src/query.ts#L473-L487](https://github.com/TanStack/query/blob/29859ae60c8dca0a5cdbf8abccc775b655cf43e2/packages/query-core/src/query.ts#L473-L487)
- Comment submission runs Detail.submitForm → updateMovie.mutate → MutationObserver.mutate → Mutation.execute; useMovie.onMutate cancels detail fetches, snapshots old data, and writes optimistic data, with rollback onError and invalidation onSettled. — [examples/react/offline/src/App.tsx#L161-L177](https://github.com/TanStack/query/blob/29859ae60c8dca0a5cdbf8abccc775b655cf43e2/examples/react/offline/src/App.tsx#L161-L177) [examples/react/offline/src/movies.ts#L22-L46](https://github.com/TanStack/query/blob/29859ae60c8dca0a5cdbf8abccc775b655cf43e2/examples/react/offline/src/movies.ts#L22-L46) [packages/query-core/src/mutationObserver.ts#L207-L221](https://github.com/TanStack/query/blob/29859ae60c8dca0a5cdbf8abccc775b655cf43e2/packages/query-core/src/mutationObserver.ts#L207-L221) [packages/query-core/src/mutation.ts#L319-L346](https://github.com/TanStack/query/blob/29859ae60c8dca0a5cdbf8abccc775b655cf43e2/packages/query-core/src/mutation.ts#L319-L346)
- Mutation completion awaits global onSuccess → local onSuccess → global onSettled → local onSettled before success dispatch; restored pending mutations skip onMutate, and finally releases the retryer and advances the scope queue. — [packages/query-core/src/mutation.ts#L316-L383](https://github.com/TanStack/query/blob/29859ae60c8dca0a5cdbf8abccc775b655cf43e2/packages/query-core/src/mutation.ts#L316-L383) [packages/query-core/src/mutation.ts#L437-L444](https://github.com/TanStack/query/blob/29859ae60c8dca0a5cdbf8abccc775b655cf43e2/packages/query-core/src/mutation.ts#L437-L444) [packages/query-core/src/mutationCache.ts#L213-L224](https://github.com/TanStack/query/blob/29859ae60c8dca0a5cdbf8abccc775b655cf43e2/packages/query-core/src/mutationCache.ts#L213-L224)
- Persistent startup runs provider restore → persister.restoreClient → timestamp/maxAge/buster checks → hydrate → awaited onSuccess → isRestoring:false → cache subscriptions; later added/removed/updated events run save → dehydrate → persistClient. — [packages/react-query-persist-client/src/PersistQueryClientProvider.tsx#L33-L48](https://github.com/TanStack/query/blob/29859ae60c8dca0a5cdbf8abccc775b655cf43e2/packages/react-query-persist-client/src/PersistQueryClientProvider.tsx#L33-L48) [packages/query-persist-client-core/src/persist.ts#L71-L104](https://github.com/TanStack/query/blob/29859ae60c8dca0a5cdbf8abccc775b655cf43e2/packages/query-persist-client-core/src/persist.ts#L71-L104) [packages/query-persist-client-core/src/persist.ts#L113-L149](https://github.com/TanStack/query/blob/29859ae60c8dca0a5cdbf8abccc775b655cf43e2/packages/query-persist-client-core/src/persist.ts#L113-L149)

Every claim links to its cited files at the pinned commit. Citations identify source evidence; they do not establish runtime correctness. Independent CodeVetter scan — not reviewed by upstream maintainers.

## Public product links

- [CodeVetter](https://codevetter.com/)
- [Download](https://codevetter.com/download)
- [Documentation](https://codevetter.com/docs/)
- [Source](https://github.com/Codevetter/codevetter)