refactor: rename cache methods for better clarity and consistency #9216
Conversation
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
Renamed cache methods in QueryCache and MutationCache to better reflect their behavior and improve developer understanding: - `QueryCache.build()` → `QueryCache.ensure()` - `MutationCache.build()` → `MutationCache.create()` - Enhanced documentation for `QueryCache.get()` to clarify retrieval-only behavior The previous naming was confusing because both `QueryCache.build()` and `MutationCache.build()` had the same name but fundamentally different behaviors: - **QueryCache.build()**: Used a "get or create" pattern - retrieved existing queries or created new ones - **MutationCache.build()**: Always created new mutation instances (since each mutation execution should be unique) This inconsistency made the API harder to understand and could lead to incorrect assumptions about behavior. ## Changes ### QueryCache - **`build()` → `ensure()`**: Better conveys "ensure this query exists" semantics - **Enhanced `get()` documentation**: Clarifies it only retrieves existing queries, returns `undefined` if not found - **Improved `ensure()` documentation**: Explains the "get or create" behavior and when to use it ### MutationCache - **`build()` → `create()`**: Clearly indicates it always creates new mutation instances - **Enhanced documentation**: Explains why mutations are always created new (each execution should be unique) ### Updated References Updated all usages across the codebase: - `packages/query-core/src/queryClient.ts` - Updated QueryCache method calls - `packages/query-core/src/queryObserver.ts` - Updated QueryCache method calls - `packages/query-core/src/mutationObserver.ts` - Updated MutationCache method calls - `packages/query-core/src/hydration.ts` - Updated both cache method calls - `packages/query-core/src/__tests__/utils.ts` - Updated test utilities - `packages/query-persist-client-core/src/__tests__/persist.test.ts` - Updated test - `packages/query-broadcast-client-experimental/src/index.ts` - Updated broadcast client
|
View your CI Pipeline Execution ↗ for commit 034d91a.
☁️ Nx Cloud last updated this comment at |
Codecov ReportAttention: Patch coverage is
Additional details and impacted files@@ Coverage Diff @@
## main #9216 +/- ##
===========================================
+ Coverage 45.30% 59.63% +14.32%
===========================================
Files 209 138 -71
Lines 8257 5495 -2762
Branches 1856 1477 -379
===========================================
- Hits 3741 3277 -464
+ Misses 4076 1921 -2155
+ Partials 440 297 -143 🚀 New features to boost your workflow:
|
braden-w
added a commit
to EpicenterHQ/query
that referenced
this pull request
May 29, 2025
…of `get` then `ensure` This commit builds on the changes from TanStack#9216. Refactored the `setQueryData` method in `QueryClient` to simplify its logic and improve readability. The previous implementation of `setQueryData` was redundant: 1. It first called `this.#queryCache.get()` to retrieve an existing query. 2. Then, it called `this.#queryCache.ensure()` which internally also performs a "get or create" operation. This meant the query was potentially being retrieved or checked for existence twice. The `ensure()` method already handles the logic of getting an existing query or creating a new one if it doesn't exist. The `setQueryData` method has been updated to: 1. Directly call `this.#queryCache.ensure()` to get or create the query. 2. Use the returned query instance to access `state.data` for the `functionalUpdate`. 3. Call `setData()` on the same query instance. **Before:** ```typescript const query = this.#queryCache.get<TInferredQueryFnData>( defaultedOptions.queryHash, ) const prevData = query?.state.data const data = functionalUpdate(updater, prevData) if (data === undefined) { return undefined } return this.#queryCache .ensure(this, defaultedOptions) .setData(data, { ...options, manual: true }) ``` **After:** ```typescript const query = this.#queryCache.ensure<TInferredQueryFnData>( this, defaultedOptions, ) const prevData = query.state.data const data = functionalUpdate(updater, prevData) if (data === undefined) { return undefined } return query.setData(data, { ...options, manual: true }) ```
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
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.
Renamed cache methods in QueryCache and MutationCache to better reflect their behavior and improve developer understanding:
QueryCache.build()→QueryCache.ensure()MutationCache.build()→MutationCache.create()QueryCache.get()to clarify retrieval-only behaviorThe previous naming was confusing because both
QueryCache.build()andMutationCache.build()had the same name but fundamentally different behaviors:This inconsistency made the API harder to understand and could lead to incorrect assumptions about behavior.
Changes
QueryCache
build()→ensure(): Better conveys "ensure this query exists" semantics, borrowing theensurepattern used inensureQueryDataandensureQueryFnget()documentation: Clarifies it only retrieves existing queries, returnsundefinedif not foundensure()documentation: Explains the "get or create" behavior and when to use itMutationCache
build()→create(): Clearly indicates it always creates new mutation instancesUpdated References
Updated all usages across the codebase:
packages/query-core/src/queryClient.ts- Updated QueryCache method callspackages/query-core/src/queryObserver.ts- Updated QueryCache method callspackages/query-core/src/mutationObserver.ts- Updated MutationCache method callspackages/query-core/src/hydration.ts- Updated both cache method callspackages/query-core/src/__tests__/utils.ts- Updated test utilitiespackages/query-persist-client-core/src/__tests__/persist.test.ts- Updated testpackages/query-broadcast-client-experimental/src/index.ts- Updated broadcast client