diff --git a/packages/query-broadcast-client-experimental/src/index.ts b/packages/query-broadcast-client-experimental/src/index.ts index e102b3c0b0..ca1e818799 100644 --- a/packages/query-broadcast-client-experimental/src/index.ts +++ b/packages/query-broadcast-client-experimental/src/index.ts @@ -78,7 +78,7 @@ export function broadcastQueryClient({ return } - queryCache.build( + queryCache.ensure( queryClient, { queryKey, @@ -95,7 +95,7 @@ export function broadcastQueryClient({ query.setState(state) return } - queryCache.build( + queryCache.ensure( queryClient, { queryKey, diff --git a/packages/query-core/src/__tests__/mutations.test.tsx b/packages/query-core/src/__tests__/mutations.test.tsx index 779daff63e..0325e30a65 100644 --- a/packages/query-core/src/__tests__/mutations.test.tsx +++ b/packages/query-core/src/__tests__/mutations.test.tsx @@ -261,7 +261,7 @@ describe('mutations', () => { const mutation = queryClient .getMutationCache() - .build( + .create( 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() diff --git a/packages/query-core/src/__tests__/utils.ts b/packages/query-core/src/__tests__/utils.ts index f9ef89d765..15338a4790 100644 --- a/packages/query-core/src/__tests__/utils.ts +++ b/packages/query-core/src/__tests__/utils.ts @@ -17,7 +17,7 @@ export function executeMutation( ) { return queryClient .getMutationCache() - .build(queryClient, options) + .create(queryClient, options) .execute(variables) } diff --git a/packages/query-core/src/hydration.ts b/packages/query-core/src/hydration.ts index 1361036d86..8092342961 100644 --- a/packages/query-core/src/hydration.ts +++ b/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, diff --git a/packages/query-core/src/mutationCache.ts b/packages/query-core/src/mutationCache.ts index 6ab95fbfed..fab531c4d7 100644 --- a/packages/query-core/src/mutationCache.ts +++ b/packages/query-core/src/mutationCache.ts @@ -93,7 +93,17 @@ export class MutationCache extends Subscribable { this.#mutationId = 0 } - build( + /** + * 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( client: QueryClient, options: MutationOptions, state?: MutationState, diff --git a/packages/query-core/src/mutationObserver.ts b/packages/query-core/src/mutationObserver.ts index 1178bbdf75..ccfe85106d 100644 --- a/packages/query-core/src/mutationObserver.ts +++ b/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) diff --git a/packages/query-core/src/queryCache.ts b/packages/query-core/src/queryCache.ts index dd7123eaac..fdb75a1b16 100644 --- a/packages/query-core/src/queryCache.ts +++ b/packages/query-core/src/queryCache.ts @@ -97,7 +97,16 @@ export class QueryCache extends Subscribable { this.#queries = new Map() } - 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 { }) } + /** + * 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, diff --git a/packages/query-core/src/queryClient.ts b/packages/query-core/src/queryClient.ts index 650d3e5ad6..2befdc378c 100644 --- a/packages/query-core/src/queryClient.ts +++ b/packages/query-core/src/queryClient.ts @@ -147,7 +147,7 @@ export class QueryClient { options: EnsureQueryDataOptions, ): Promise { 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), diff --git a/packages/query-core/src/queryObserver.ts b/packages/query-core/src/queryObserver.ts index f2b961eb27..9781aedc84 100644 --- a/packages/query-core/src/queryObserver.ts +++ b/packages/query-core/src/queryObserver.ts @@ -232,7 +232,7 @@ export class QueryObserver< TQueryKey >, ): QueryObserverResult { - 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 diff --git a/packages/query-persist-client-core/src/__tests__/persist.test.ts b/packages/query-persist-client-core/src/__tests__/persist.test.ts index 14f7d0720b..4133ac1b5c 100644 --- a/packages/query-persist-client-core/src/__tests__/persist.test.ts +++ b/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), })