refactor: rename cache methods for better clarity and consistency

packages/query-broadcast-client-experimental/src/index.ts

@@ -78,7 +78,7 @@
           return
         }
 
-        queryCache.build(
+        queryCache.ensure(
           queryClient,
           {
             queryKey,
@@ -95,7 +95,7 @@
           query.setState(state)
           return
         }
-        queryCache.build(
+        queryCache.ensure(
           queryClient,
           {
             queryKey,

packages/query-core/src/__tests__/mutations.test.tsx

@@ -261,7 +261,7 @@ describe('mutations', () => {
 
     const mutation = queryClient
       .getMutationCache()
-      .build<string, unknown, string, string>(
+      .create<string, unknown, string, string>(
         queryClient,
         {
           mutationKey: key,
@@ -329,7 +329,7 @@ describe('mutations', () => {
   test('addObserver should not add an existing observer', () => {
     const mutationCache = queryClient.getMutationCache()
     const observer = new MutationObserver(queryClient, {})
-    const currentMutation = mutationCache.build(queryClient, {})
+    const currentMutation = mutationCache.create(queryClient, {})
 
     const fn = vi.fn()
 

packages/query-core/src/__tests__/utils.ts

@@ -17,7 +17,7 @@ export function executeMutation<TVariables>(
 ) {
   return queryClient
     .getMutationCache()
-    .build(queryClient, options)
+    .create(queryClient, options)
     .execute(variables)
 }
 

packages/query-core/src/hydration.ts

@@ -184,7 +184,7 @@ export function hydrate(
   const queries = (dehydratedState as DehydratedState).queries || []
 
   mutations.forEach(({ state, ...mutationOptions }) => {
-    mutationCache.build(
+    mutationCache.create(
       client,
       {
         ...client.getDefaultOptions().hydrate?.mutations,
@@ -227,7 +227,7 @@ export function hydrate(
         }
       } else {
         // Restore query
-        query = queryCache.build(
+        query = queryCache.ensure(
           client,
           {
             ...client.getDefaultOptions().hydrate?.queries,

packages/query-core/src/mutationCache.ts

@@ -93,7 +93,17 @@ export class MutationCache extends Subscribable<MutationCacheListener> {
     this.#mutationId = 0
   }
 
-  build<TData, TError, TVariables, TContext>(
+  /**
+   * Creates a new mutation instance and adds it to the cache.
+   * Unlike QueryCache.ensure(), this always creates a new mutation since
+   * each mutation execution should be unique.
+   *
+   * @param client - The QueryClient instance
+   * @param options - Mutation options
+   * @param state - Optional initial state for the new mutation
+   * @returns A new Mutation instance
+   */
+  create<TData, TError, TVariables, TContext>(
     client: QueryClient,
     options: MutationOptions<TData, TError, TVariables, TContext>,
     state?: MutationState<TData, TError, TVariables, TContext>,

packages/query-core/src/mutationObserver.ts

@@ -118,7 +118,7 @@ export class MutationObserver<
 
     this.#currentMutation = this.#client
       .getMutationCache()
-      .build(this.#client, this.options)
+      .create(this.#client, this.options)
 
     this.#currentMutation.addObserver(this)
 

packages/query-core/src/queryCache.ts

@@ -97,7 +97,16 @@ export class QueryCache extends Subscribable<QueryCacheListener> {
     this.#queries = new Map<string, Query>()
   }
 
-  build<
+  /**
+   * Ensures a query exists in the cache, creating it if it doesn't exist.
+   * This is the primary method for ensuring a query exists in the cache.
+   *
+   * @param client - The QueryClient instance
+   * @param options - Query options including the queryKey
+   * @param state - Optional initial state for newly created queries
+   * @returns Always returns a Query instance (creates one if needed)
+   */
+  ensure<
     TQueryFnData = unknown,
     TError = DefaultError,
     TData = TQueryFnData,
@@ -163,6 +172,12 @@ export class QueryCache extends Subscribable<QueryCacheListener> {
     })
   }
 
+  /**
+   * Retrieves an existing query from the cache by its hash.
+   *
+   * @param queryHash - The hash string identifying the query
+   * @returns The existing Query instance, or undefined if not found
+   */
   get<
     TQueryFnData = unknown,
     TError = DefaultError,

packages/query-core/src/queryClient.ts

@@ -147,7 +147,7 @@ export class QueryClient {
     options: EnsureQueryDataOptions<TQueryFnData, TError, TData, TQueryKey>,
   ): Promise<TData> {
     const defaultedOptions = this.defaultQueryOptions(options)
-    const query = this.#queryCache.build(this, defaultedOptions)
+    const query = this.#queryCache.ensure(this, defaultedOptions)
     const cachedData = query.state.data
 
     if (cachedData === undefined) {
@@ -205,7 +205,7 @@ export class QueryClient {
     }
 
     return this.#queryCache
-      .build(this, defaultedOptions)
+      .ensure(this, defaultedOptions)
       .setData(data, { ...options, manual: true })
   }
 
@@ -361,7 +361,7 @@ export class QueryClient {
       defaultedOptions.retry = false
     }
 
-    const query = this.#queryCache.build(this, defaultedOptions)
+    const query = this.#queryCache.ensure(this, defaultedOptions)
 
     return query.isStaleByTime(
       resolveStaleTime(defaultedOptions.staleTime, query),

packages/query-core/src/queryObserver.ts

@@ -232,7 +232,7 @@ export class QueryObserver<
       TQueryKey
     >,
   ): QueryObserverResult<TData, TError> {
-    const query = this.#client.getQueryCache().build(this.#client, options)
+    const query = this.#client.getQueryCache().ensure(this.#client, options)
 
     const result = this.createResult(query, options)
 
@@ -306,7 +306,7 @@ export class QueryObserver<
 
     const query = this.#client
       .getQueryCache()
-      .build(this.#client, defaultedOptions)
+      .ensure(this.#client, defaultedOptions)
 
     return query.fetch().then(() => this.createResult(query, defaultedOptions))
   }
@@ -691,7 +691,9 @@ export class QueryObserver<
   }
 
   #updateQuery(): void {
-    const query = this.#client.getQueryCache().build(this.#client, this.options)
+    const query = this.#client
+      .getQueryCache()
+      .ensure(this.#client, this.options)
 
     if (query === this.#currentQuery) {
       return

packages/query-persist-client-core/src/__tests__/persist.test.ts

@@ -18,7 +18,7 @@ describe('persistQueryClientSubscribe', () => {
       dehydrateOptions: { shouldDehydrateMutation: () => true },
     })
 
-    queryClient.getMutationCache().build(queryClient, {
+    queryClient.getMutationCache().create(queryClient, {
       mutationFn: (text: string) => Promise.resolve(text),
     })