@tanstack/solid-query 6.0.0-rc.1 → 6.0.0-rc.3

package/build/_tsup-dts-rollup.d.cts

@@ -251,6 +251,33 @@ export { DehydratedState }
 
 export { DehydrateOptions }
 
+/**
+ * Waits for every fetch the client has in flight to settle, then
+ * dehydrates. This is the extraction half of a single-flight collector:
+ * after route data functions run for the mutation's target URL, loaders
+ * commonly kick off prefetches without awaiting them — plain
+ * `dehydrate()` would snapshot those mid-fetch and ship nothing.
+ *
+ * ```ts
+ * registerFlightDataSource(FLIGHT_DATA_SOURCE, (event, outcome) =>
+ *   loadFlightTarget({
+ *     router,
+ *     event,
+ *     outcome,
+ *     collect: () => dehydrateSettled(queryClient),
+ *   }),
+ * )
+ * ```
+ *
+ * Settling is chased to quiescence — awaiting one batch of fetches can
+ * dispatch more (dependent queries keyed off a first result) — so an
+ * unconditionally self-refetching query would keep this pending; that's
+ * an app bug mirrored, not guarded.
+ */
+declare function dehydrateSettled(client: QueryClient, options?: DehydrateOptions): Promise<DehydratedState>;
+export { dehydrateSettled }
+export { dehydrateSettled as dehydrateSettled_alias_1 }
+
 export { DistributiveOmit }
 
 export { EnsureInfiniteQueryDataOptions }
@@ -271,6 +298,40 @@ export { FetchQueryOptions }
 
 export { FetchStatus }
 
+/**
+ * The query cache's single-flight source id. Mutation responses can fold
+ * fresh data for multiple caches at once (Solid's multi-source
+ * single-flight protocol); this is the slice the query cache claims — the
+ * provider subscribes its consumer under it, and server collectors
+ * register under it to produce the data:
+ *
+ * ```ts
+ * import { registerFlightDataSource } from '@solidjs/web/server-functions/server'
+ * import { FLIGHT_DATA_SOURCE, dehydrate } from '@tanstack/solid-query'
+ *
+ * registerFlightDataSource(FLIGHT_DATA_SOURCE, async (event, outcome) => {
+ *   // rebuild the data for outcome.targetUrl into a QueryClient, then
+ *   return dehydrate(queryClient)
+ * })
+ * ```
+ *
+ * The slice's payload is a `DehydratedState`; the provider consumes it
+ * with `hydrate()`, so every mounted query on those keys updates before
+ * the mutation's promise resolves — no follow-up refetches.
+ *
+ * A mutation can additionally declare its invalidation SCOPE with
+ * `X-Revalidate` keys (the `revalidate` option of Solid's `reload`/
+ * `redirect` response helpers). The payload covers the slice of that scope
+ * the server could recompute; whatever a declared key matches beyond it is
+ * swept client-side (see the consumer below). For the sweep to be
+ * delivered, the collector must contribute a slice — return the dehydrated
+ * state even when it holds no queries if `outcome.revalidateKeys` is
+ * present, rather than skipping the source.
+ */
+declare const FLIGHT_DATA_SOURCE = "sq";
+export { FLIGHT_DATA_SOURCE }
+export { FLIGHT_DATA_SOURCE as FLIGHT_DATA_SOURCE_alias_1 }
+
 export { focusManager }
 
 export { GetNextPageParamFunction }
@@ -555,8 +616,14 @@ export { QueryClientContext as QueryClientContext_alias_1 }
 /**
  * Provides the QueryClient and manages its mount lifecycle. On the server
  * it also registers the cache serializer above; on the client, hooks prime
- * the cache from their hash-keyed registry entries themselves — see
- * `useBaseQuery`.
+ * the cache from their hash-keyed registry entries themselves (see
+ * `useBaseQuery`) and the provider subscribes the cache's single-flight
+ * consumer: mutation responses carrying a `FLIGHT_DATA_SOURCE` slice (a
+ * `DehydratedState` produced by a server collector registered under the
+ * same id) hydrate this client before the mutation's promise resolves.
+ * Subscribing is inert when no server collector exists — the server just
+ * folds nothing — so it is unconditional. One consumer per source: with
+ * nested providers, the innermost mounted one owns the slice.
  */
 declare const QueryClientProvider: (props: QueryClientProviderProps) => JSX.Element;
 export { QueryClientProvider }

package/build/_tsup-dts-rollup.d.ts

@@ -251,6 +251,33 @@ export { DehydratedState }
 
 export { DehydrateOptions }
 
+/**
+ * Waits for every fetch the client has in flight to settle, then
+ * dehydrates. This is the extraction half of a single-flight collector:
+ * after route data functions run for the mutation's target URL, loaders
+ * commonly kick off prefetches without awaiting them — plain
+ * `dehydrate()` would snapshot those mid-fetch and ship nothing.
+ *
+ * ```ts
+ * registerFlightDataSource(FLIGHT_DATA_SOURCE, (event, outcome) =>
+ *   loadFlightTarget({
+ *     router,
+ *     event,
+ *     outcome,
+ *     collect: () => dehydrateSettled(queryClient),
+ *   }),
+ * )
+ * ```
+ *
+ * Settling is chased to quiescence — awaiting one batch of fetches can
+ * dispatch more (dependent queries keyed off a first result) — so an
+ * unconditionally self-refetching query would keep this pending; that's
+ * an app bug mirrored, not guarded.
+ */
+declare function dehydrateSettled(client: QueryClient, options?: DehydrateOptions): Promise<DehydratedState>;
+export { dehydrateSettled }
+export { dehydrateSettled as dehydrateSettled_alias_1 }
+
 export { DistributiveOmit }
 
 export { EnsureInfiniteQueryDataOptions }
@@ -271,6 +298,40 @@ export { FetchQueryOptions }
 
 export { FetchStatus }
 
+/**
+ * The query cache's single-flight source id. Mutation responses can fold
+ * fresh data for multiple caches at once (Solid's multi-source
+ * single-flight protocol); this is the slice the query cache claims — the
+ * provider subscribes its consumer under it, and server collectors
+ * register under it to produce the data:
+ *
+ * ```ts
+ * import { registerFlightDataSource } from '@solidjs/web/server-functions/server'
+ * import { FLIGHT_DATA_SOURCE, dehydrate } from '@tanstack/solid-query'
+ *
+ * registerFlightDataSource(FLIGHT_DATA_SOURCE, async (event, outcome) => {
+ *   // rebuild the data for outcome.targetUrl into a QueryClient, then
+ *   return dehydrate(queryClient)
+ * })
+ * ```
+ *
+ * The slice's payload is a `DehydratedState`; the provider consumes it
+ * with `hydrate()`, so every mounted query on those keys updates before
+ * the mutation's promise resolves — no follow-up refetches.
+ *
+ * A mutation can additionally declare its invalidation SCOPE with
+ * `X-Revalidate` keys (the `revalidate` option of Solid's `reload`/
+ * `redirect` response helpers). The payload covers the slice of that scope
+ * the server could recompute; whatever a declared key matches beyond it is
+ * swept client-side (see the consumer below). For the sweep to be
+ * delivered, the collector must contribute a slice — return the dehydrated
+ * state even when it holds no queries if `outcome.revalidateKeys` is
+ * present, rather than skipping the source.
+ */
+declare const FLIGHT_DATA_SOURCE = "sq";
+export { FLIGHT_DATA_SOURCE }
+export { FLIGHT_DATA_SOURCE as FLIGHT_DATA_SOURCE_alias_1 }
+
 export { focusManager }
 
 export { GetNextPageParamFunction }
@@ -555,8 +616,14 @@ export { QueryClientContext as QueryClientContext_alias_1 }
 /**
  * Provides the QueryClient and manages its mount lifecycle. On the server
  * it also registers the cache serializer above; on the client, hooks prime
- * the cache from their hash-keyed registry entries themselves — see
- * `useBaseQuery`.
+ * the cache from their hash-keyed registry entries themselves (see
+ * `useBaseQuery`) and the provider subscribes the cache's single-flight
+ * consumer: mutation responses carrying a `FLIGHT_DATA_SOURCE` slice (a
+ * `DehydratedState` produced by a server collector registered under the
+ * same id) hydrate this client before the mutation's promise resolves.
+ * Subscribing is inert when no server collector exists — the server just
+ * folds nothing — so it is unconditional. One consumer per source: with
+ * nested providers, the innermost mounted one owns the slice.
  */
 declare const QueryClientProvider: (props: QueryClientProviderProps) => JSX.Element;
 export { QueryClientProvider }

package/build/dev.cjs

@@ -3,6 +3,7 @@
 var queryCore = require('@tanstack/query-core');
 var solidJs = require('solid-js');
 var web = require('@solidjs/web');
+var serverFunctions = require('@solidjs/web/server-functions');
 
 // src/index.ts
 exports.QueryClient = class QueryClient extends queryCore.QueryClient {
@@ -12,6 +13,18 @@ exports.QueryClient = class QueryClient extends queryCore.QueryClient {
 };
 var isServer = typeof window === "undefined";
 var HYDRATION_KEY_PREFIX = "sq:";
+exports.FLIGHT_DATA_SOURCE = "sq";
+function sweepRevalidatedQueries(client, payload, response) {
+  const keys = response.headers.get(web.REVALIDATE_HEADER)?.split(",");
+  if (!keys) return;
+  const covered = new Set(payload.queries.map((query) => query.queryHash));
+  for (const key of keys) {
+    client.invalidateQueries({
+      queryKey: [key],
+      predicate: (query) => !covered.has(query.queryHash)
+    }).catch(() => void 0);
+  }
+}
 exports.QueryClientContext = solidJs.createContext(null);
 exports.useQueryClient = (queryClient) => {
   if (queryClient) {
@@ -27,9 +40,11 @@ function serializeCacheOnServer(client) {
   const ctx = solidJs.sharedConfig.context;
   if (!ctx || !ctx.async || ctx.noHydrate) return;
   const cache = client.getQueryCache();
+  const shouldDehydrateQuery = client.getDefaultOptions().dehydrate?.shouldDehydrateQuery;
   const seen = /* @__PURE__ */ new Set();
   const serializeQuery = (query) => {
     if (seen.has(query.queryHash)) return;
+    if (shouldDehydrateQuery && !shouldDehydrateQuery(query)) return;
     const state = query.state;
     if (state.status === "success") {
       seen.add(query.queryHash);
@@ -53,7 +68,18 @@ function serializeCacheOnServer(client) {
 exports.QueryClientProvider = (props) => {
   props.client.mount();
   solidJs.onCleanup(() => props.client.unmount());
-  if (isServer) serializeCacheOnServer(props.client);
+  if (isServer) {
+    serializeCacheOnServer(props.client);
+    solidJs.onCleanup(() => {
+      props.client.cancelQueries().catch(() => void 0);
+      props.client.clear();
+    });
+  } else {
+    solidJs.onCleanup(serverFunctions.subscribeFlightData(exports.FLIGHT_DATA_SOURCE, (data, context) => {
+      queryCore.hydrate(props.client, data);
+      sweepRevalidatedQueries(props.client, data, context.response);
+    }));
+  }
   return web.createComponent(exports.QueryClientContext, {
     value: () => props.client,
     get children() {
@@ -432,6 +458,15 @@ function useQuery(options, queryClient) {
 function queryOptions(options) {
   return options;
 }
+async function dehydrateSettled(client, options) {
+  const cache = client.getQueryCache();
+  for (; ; ) {
+    const pending = cache.getAll().filter((query) => query.state.fetchStatus !== "idle").map((query) => query.promise);
+    if (pending.length === 0) break;
+    await Promise.allSettled(pending);
+  }
+  return queryCore.dehydrate(client, options);
+}
 var isServer3 = typeof window === "undefined";
 function createCacheAggregate(subscribe, read, empty) {
   const hydratedMount = !isServer3 && solidJs.sharedConfig.hydrating === true;
@@ -592,15 +627,13 @@ function useMutation(options, queryClient) {
   const [flight, setFlight] = solidJs.createOptimistic(null);
   const [settled, setSettled] = solidJs.createSignal(IDLE);
   let activeMutation = null;
+  let unsubscribeFlight = null;
   const [flightVersion, setFlightVersion] = solidJs.createSignal(0);
-  if (!isServer4) {
-    const unsubscribe = client().getMutationCache().subscribe((event) => {
-      if ("mutation" in event && event.mutation === activeMutation) {
-        setFlightVersion((v) => v + 1);
-      }
+  if (!isServer4)
+    solidJs.onCleanup(() => {
+      unsubscribeFlight?.();
+      unsubscribeFlight = null;
     });
-    solidJs.onCleanup(unsubscribe);
-  }
   async function* run(variables) {
     const opts = solidJs.untrack(options);
     const callbackContext = {
@@ -610,7 +643,8 @@ function useMutation(options, queryClient) {
     };
     if (!isServer4) setFlight({ variables });
     opts.onMutate?.(variables, callbackContext);
-    const mutation = client().getMutationCache().build(client(), {
+    const c = solidJs.untrack(client);
+    const mutation = c.getMutationCache().build(c, {
       ...opts,
       // Options-level callbacks re-run below, inside the transaction —
       // executing them here (inside the await gap) would let their
@@ -621,6 +655,20 @@ function useMutation(options, queryClient) {
       onSettled: void 0
     });
     activeMutation = mutation;
+    if (!isServer4) {
+      unsubscribeFlight?.();
+      unsubscribeFlight = c.getMutationCache().subscribe((event) => {
+        if ("mutation" in event && event.mutation === activeMutation) {
+          setFlightVersion((v) => v + 1);
+        }
+      });
+    }
+    const settleFlight = () => {
+      if (activeMutation !== mutation) return;
+      activeMutation = null;
+      unsubscribeFlight?.();
+      unsubscribeFlight = null;
+    };
     async function* settleFailure(error) {
       try {
         if (opts.onError)
@@ -648,7 +696,7 @@ function useMutation(options, queryClient) {
           variables,
           submittedAt: mutation.state.submittedAt
         });
-      activeMutation = null;
+      settleFlight();
       throw error;
     }
     let result2;
@@ -688,7 +736,7 @@ function useMutation(options, queryClient) {
         variables,
         submittedAt: mutation.state.submittedAt
       });
-    activeMutation = null;
+    settleFlight();
     return result2;
   }
   const invoke = isServer4 ? (variables) => drain(run(variables)) : solidJs.action(run);
@@ -826,6 +874,7 @@ function useQueries(queriesOptions, queryClient) {
   });
 }
 
+exports.dehydrateSettled = dehydrateSettled;
 exports.infiniteQueryOptions = infiniteQueryOptions;
 exports.mutationOptions = mutationOptions;
 exports.queryOptions = queryOptions;

package/build/dev.d.cts

@@ -23,10 +23,12 @@ export { useQuery } from './_tsup-dts-rollup.cjs';
 export { queryOptions } from './_tsup-dts-rollup.cjs';
 export { DefinedInitialDataOptions } from './_tsup-dts-rollup.cjs';
 export { UndefinedInitialDataOptions } from './_tsup-dts-rollup.cjs';
+export { FLIGHT_DATA_SOURCE_alias_1 as FLIGHT_DATA_SOURCE } from './_tsup-dts-rollup.cjs';
 export { QueryClientContext_alias_1 as QueryClientContext } from './_tsup-dts-rollup.cjs';
 export { QueryClientProvider_alias_1 as QueryClientProvider } from './_tsup-dts-rollup.cjs';
 export { useQueryClient_alias_1 as useQueryClient } from './_tsup-dts-rollup.cjs';
 export { QueryClientProviderProps_alias_1 as QueryClientProviderProps } from './_tsup-dts-rollup.cjs';
+export { dehydrateSettled_alias_1 as dehydrateSettled } from './_tsup-dts-rollup.cjs';
 export { useIsFetching } from './_tsup-dts-rollup.cjs';
 export { useInfiniteQuery } from './_tsup-dts-rollup.cjs';
 export { infiniteQueryOptions } from './_tsup-dts-rollup.cjs';

package/build/dev.d.ts

@@ -23,10 +23,12 @@ export { useQuery } from './_tsup-dts-rollup.js';
 export { queryOptions } from './_tsup-dts-rollup.js';
 export { DefinedInitialDataOptions } from './_tsup-dts-rollup.js';
 export { UndefinedInitialDataOptions } from './_tsup-dts-rollup.js';
+export { FLIGHT_DATA_SOURCE_alias_1 as FLIGHT_DATA_SOURCE } from './_tsup-dts-rollup.js';
 export { QueryClientContext_alias_1 as QueryClientContext } from './_tsup-dts-rollup.js';
 export { QueryClientProvider_alias_1 as QueryClientProvider } from './_tsup-dts-rollup.js';
 export { useQueryClient_alias_1 as useQueryClient } from './_tsup-dts-rollup.js';
 export { QueryClientProviderProps_alias_1 as QueryClientProviderProps } from './_tsup-dts-rollup.js';
+export { dehydrateSettled_alias_1 as dehydrateSettled } from './_tsup-dts-rollup.js';
 export { useIsFetching } from './_tsup-dts-rollup.js';
 export { useInfiniteQuery } from './_tsup-dts-rollup.js';
 export { infiniteQueryOptions } from './_tsup-dts-rollup.js';

package/build/dev.js

@@ -1,7 +1,8 @@
-import { noop, QueryClient as QueryClient$1, shouldThrowError, InfiniteQueryObserver, hydrate, QueryObserver, replaceEqualDeep } from '@tanstack/query-core';
+import { noop, QueryClient as QueryClient$1, hydrate, dehydrate, shouldThrowError, InfiniteQueryObserver, QueryObserver, replaceEqualDeep } from '@tanstack/query-core';
 export * from '@tanstack/query-core';
 import { createContext, useContext, onCleanup, createMemo, createOptimistic, createSignal, action, createRenderEffect, untrack, repeat, $TRACK, sharedConfig, createEffect, createProjection, runWithOwner, isPending, resolve } from 'solid-js';
-import { createComponent } from '@solidjs/web';
+import { createComponent, REVALIDATE_HEADER } from '@solidjs/web';
+import { subscribeFlightData } from '@solidjs/web/server-functions';
 
 // src/index.ts
 var QueryClient = class extends QueryClient$1 {
@@ -11,6 +12,18 @@ var QueryClient = class extends QueryClient$1 {
 };
 var isServer = typeof window === "undefined";
 var HYDRATION_KEY_PREFIX = "sq:";
+var FLIGHT_DATA_SOURCE = "sq";
+function sweepRevalidatedQueries(client, payload, response) {
+  const keys = response.headers.get(REVALIDATE_HEADER)?.split(",");
+  if (!keys) return;
+  const covered = new Set(payload.queries.map((query) => query.queryHash));
+  for (const key of keys) {
+    client.invalidateQueries({
+      queryKey: [key],
+      predicate: (query) => !covered.has(query.queryHash)
+    }).catch(() => void 0);
+  }
+}
 var QueryClientContext = createContext(null);
 var useQueryClient = (queryClient) => {
   if (queryClient) {
@@ -26,9 +39,11 @@ function serializeCacheOnServer(client) {
   const ctx = sharedConfig.context;
   if (!ctx || !ctx.async || ctx.noHydrate) return;
   const cache = client.getQueryCache();
+  const shouldDehydrateQuery = client.getDefaultOptions().dehydrate?.shouldDehydrateQuery;
   const seen = /* @__PURE__ */ new Set();
   const serializeQuery = (query) => {
     if (seen.has(query.queryHash)) return;
+    if (shouldDehydrateQuery && !shouldDehydrateQuery(query)) return;
     const state = query.state;
     if (state.status === "success") {
       seen.add(query.queryHash);
@@ -52,7 +67,18 @@ function serializeCacheOnServer(client) {
 var QueryClientProvider = (props) => {
   props.client.mount();
   onCleanup(() => props.client.unmount());
-  if (isServer) serializeCacheOnServer(props.client);
+  if (isServer) {
+    serializeCacheOnServer(props.client);
+    onCleanup(() => {
+      props.client.cancelQueries().catch(() => void 0);
+      props.client.clear();
+    });
+  } else {
+    onCleanup(subscribeFlightData(FLIGHT_DATA_SOURCE, (data, context) => {
+      hydrate(props.client, data);
+      sweepRevalidatedQueries(props.client, data, context.response);
+    }));
+  }
   return createComponent(QueryClientContext, {
     value: () => props.client,
     get children() {
@@ -431,6 +457,15 @@ function useQuery(options, queryClient) {
 function queryOptions(options) {
   return options;
 }
+async function dehydrateSettled(client, options) {
+  const cache = client.getQueryCache();
+  for (; ; ) {
+    const pending = cache.getAll().filter((query) => query.state.fetchStatus !== "idle").map((query) => query.promise);
+    if (pending.length === 0) break;
+    await Promise.allSettled(pending);
+  }
+  return dehydrate(client, options);
+}
 var isServer3 = typeof window === "undefined";
 function createCacheAggregate(subscribe, read, empty) {
   const hydratedMount = !isServer3 && sharedConfig.hydrating === true;
@@ -591,15 +626,13 @@ function useMutation(options, queryClient) {
   const [flight, setFlight] = createOptimistic(null);
   const [settled, setSettled] = createSignal(IDLE);
   let activeMutation = null;
+  let unsubscribeFlight = null;
   const [flightVersion, setFlightVersion] = createSignal(0);
-  if (!isServer4) {
-    const unsubscribe = client().getMutationCache().subscribe((event) => {
-      if ("mutation" in event && event.mutation === activeMutation) {
-        setFlightVersion((v) => v + 1);
-      }
+  if (!isServer4)
+    onCleanup(() => {
+      unsubscribeFlight?.();
+      unsubscribeFlight = null;
     });
-    onCleanup(unsubscribe);
-  }
   async function* run(variables) {
     const opts = untrack(options);
     const callbackContext = {
@@ -609,7 +642,8 @@ function useMutation(options, queryClient) {
     };
     if (!isServer4) setFlight({ variables });
     opts.onMutate?.(variables, callbackContext);
-    const mutation = client().getMutationCache().build(client(), {
+    const c = untrack(client);
+    const mutation = c.getMutationCache().build(c, {
       ...opts,
       // Options-level callbacks re-run below, inside the transaction —
       // executing them here (inside the await gap) would let their
@@ -620,6 +654,20 @@ function useMutation(options, queryClient) {
       onSettled: void 0
     });
     activeMutation = mutation;
+    if (!isServer4) {
+      unsubscribeFlight?.();
+      unsubscribeFlight = c.getMutationCache().subscribe((event) => {
+        if ("mutation" in event && event.mutation === activeMutation) {
+          setFlightVersion((v) => v + 1);
+        }
+      });
+    }
+    const settleFlight = () => {
+      if (activeMutation !== mutation) return;
+      activeMutation = null;
+      unsubscribeFlight?.();
+      unsubscribeFlight = null;
+    };
     async function* settleFailure(error) {
       try {
         if (opts.onError)
@@ -647,7 +695,7 @@ function useMutation(options, queryClient) {
           variables,
           submittedAt: mutation.state.submittedAt
         });
-      activeMutation = null;
+      settleFlight();
       throw error;
     }
     let result2;
@@ -687,7 +735,7 @@ function useMutation(options, queryClient) {
         variables,
         submittedAt: mutation.state.submittedAt
       });
-    activeMutation = null;
+    settleFlight();
     return result2;
   }
   const invoke = isServer4 ? (variables) => drain(run(variables)) : action(run);
@@ -825,4 +873,4 @@ function useQueries(queriesOptions, queryClient) {
   });
 }
 
-export { IsRestoringContext, QueryClient, QueryClientContext, QueryClientProvider, infiniteQueryOptions, mutationOptions, queryOptions, useInfiniteQuery, useIsFetching, useIsMutating, useIsRestoring, useMutation, useMutationState, useQueries, useQuery, useQueryClient };
+export { FLIGHT_DATA_SOURCE, IsRestoringContext, QueryClient, QueryClientContext, QueryClientProvider, dehydrateSettled, infiniteQueryOptions, mutationOptions, queryOptions, useInfiniteQuery, useIsFetching, useIsMutating, useIsRestoring, useMutation, useMutationState, useQueries, useQuery, useQueryClient };

package/build/index.cjs

@@ -3,6 +3,7 @@
 var queryCore = require('@tanstack/query-core');
 var solidJs = require('solid-js');
 var web = require('@solidjs/web');
+var serverFunctions = require('@solidjs/web/server-functions');
 
 // src/index.ts
 exports.QueryClient = class QueryClient extends queryCore.QueryClient {
@@ -12,6 +13,18 @@ exports.QueryClient = class QueryClient extends queryCore.QueryClient {
 };
 var isServer = typeof window === "undefined";
 var HYDRATION_KEY_PREFIX = "sq:";
+exports.FLIGHT_DATA_SOURCE = "sq";
+function sweepRevalidatedQueries(client, payload, response) {
+  const keys = response.headers.get(web.REVALIDATE_HEADER)?.split(",");
+  if (!keys) return;
+  const covered = new Set(payload.queries.map((query) => query.queryHash));
+  for (const key of keys) {
+    client.invalidateQueries({
+      queryKey: [key],
+      predicate: (query) => !covered.has(query.queryHash)
+    }).catch(() => void 0);
+  }
+}
 exports.QueryClientContext = solidJs.createContext(null);
 exports.useQueryClient = (queryClient) => {
   if (queryClient) {
@@ -27,9 +40,11 @@ function serializeCacheOnServer(client) {
   const ctx = solidJs.sharedConfig.context;
   if (!ctx || !ctx.async || ctx.noHydrate) return;
   const cache = client.getQueryCache();
+  const shouldDehydrateQuery = client.getDefaultOptions().dehydrate?.shouldDehydrateQuery;
   const seen = /* @__PURE__ */ new Set();
   const serializeQuery = (query) => {
     if (seen.has(query.queryHash)) return;
+    if (shouldDehydrateQuery && !shouldDehydrateQuery(query)) return;
     const state = query.state;
     if (state.status === "success") {
       seen.add(query.queryHash);
@@ -53,7 +68,18 @@ function serializeCacheOnServer(client) {
 exports.QueryClientProvider = (props) => {
   props.client.mount();
   solidJs.onCleanup(() => props.client.unmount());
-  if (isServer) serializeCacheOnServer(props.client);
+  if (isServer) {
+    serializeCacheOnServer(props.client);
+    solidJs.onCleanup(() => {
+      props.client.cancelQueries().catch(() => void 0);
+      props.client.clear();
+    });
+  } else {
+    solidJs.onCleanup(serverFunctions.subscribeFlightData(exports.FLIGHT_DATA_SOURCE, (data, context) => {
+      queryCore.hydrate(props.client, data);
+      sweepRevalidatedQueries(props.client, data, context.response);
+    }));
+  }
   return web.createComponent(exports.QueryClientContext, {
     value: () => props.client,
     get children() {
@@ -432,6 +458,15 @@ function useQuery(options, queryClient) {
 function queryOptions(options) {
   return options;
 }
+async function dehydrateSettled(client, options) {
+  const cache = client.getQueryCache();
+  for (; ; ) {
+    const pending = cache.getAll().filter((query) => query.state.fetchStatus !== "idle").map((query) => query.promise);
+    if (pending.length === 0) break;
+    await Promise.allSettled(pending);
+  }
+  return queryCore.dehydrate(client, options);
+}
 var isServer3 = typeof window === "undefined";
 function createCacheAggregate(subscribe, read, empty) {
   const hydratedMount = !isServer3 && solidJs.sharedConfig.hydrating === true;
@@ -592,15 +627,13 @@ function useMutation(options, queryClient) {
   const [flight, setFlight] = solidJs.createOptimistic(null);
   const [settled, setSettled] = solidJs.createSignal(IDLE);
   let activeMutation = null;
+  let unsubscribeFlight = null;
   const [flightVersion, setFlightVersion] = solidJs.createSignal(0);
-  if (!isServer4) {
-    const unsubscribe = client().getMutationCache().subscribe((event) => {
-      if ("mutation" in event && event.mutation === activeMutation) {
-        setFlightVersion((v) => v + 1);
-      }
+  if (!isServer4)
+    solidJs.onCleanup(() => {
+      unsubscribeFlight?.();
+      unsubscribeFlight = null;
     });
-    solidJs.onCleanup(unsubscribe);
-  }
   async function* run(variables) {
     const opts = solidJs.untrack(options);
     const callbackContext = {
@@ -610,7 +643,8 @@ function useMutation(options, queryClient) {
     };
     if (!isServer4) setFlight({ variables });
     opts.onMutate?.(variables, callbackContext);
-    const mutation = client().getMutationCache().build(client(), {
+    const c = solidJs.untrack(client);
+    const mutation = c.getMutationCache().build(c, {
       ...opts,
       // Options-level callbacks re-run below, inside the transaction —
       // executing them here (inside the await gap) would let their
@@ -621,6 +655,20 @@ function useMutation(options, queryClient) {
       onSettled: void 0
     });
     activeMutation = mutation;
+    if (!isServer4) {
+      unsubscribeFlight?.();
+      unsubscribeFlight = c.getMutationCache().subscribe((event) => {
+        if ("mutation" in event && event.mutation === activeMutation) {
+          setFlightVersion((v) => v + 1);
+        }
+      });
+    }
+    const settleFlight = () => {
+      if (activeMutation !== mutation) return;
+      activeMutation = null;
+      unsubscribeFlight?.();
+      unsubscribeFlight = null;
+    };
     async function* settleFailure(error) {
       try {
         if (opts.onError)
@@ -648,7 +696,7 @@ function useMutation(options, queryClient) {
           variables,
           submittedAt: mutation.state.submittedAt
         });
-      activeMutation = null;
+      settleFlight();
       throw error;
     }
     let result2;
@@ -688,7 +736,7 @@ function useMutation(options, queryClient) {
         variables,
         submittedAt: mutation.state.submittedAt
       });
-    activeMutation = null;
+    settleFlight();
     return result2;
   }
   const invoke = isServer4 ? (variables) => drain(run(variables)) : solidJs.action(run);
@@ -826,6 +874,7 @@ function useQueries(queriesOptions, queryClient) {
   });
 }
 
+exports.dehydrateSettled = dehydrateSettled;
 exports.infiniteQueryOptions = infiniteQueryOptions;
 exports.mutationOptions = mutationOptions;
 exports.queryOptions = queryOptions;

package/build/index.d.cts

@@ -23,10 +23,12 @@ export { useQuery } from './_tsup-dts-rollup.cjs';
 export { queryOptions } from './_tsup-dts-rollup.cjs';
 export { DefinedInitialDataOptions } from './_tsup-dts-rollup.cjs';
 export { UndefinedInitialDataOptions } from './_tsup-dts-rollup.cjs';
+export { FLIGHT_DATA_SOURCE_alias_1 as FLIGHT_DATA_SOURCE } from './_tsup-dts-rollup.cjs';
 export { QueryClientContext_alias_1 as QueryClientContext } from './_tsup-dts-rollup.cjs';
 export { QueryClientProvider_alias_1 as QueryClientProvider } from './_tsup-dts-rollup.cjs';
 export { useQueryClient_alias_1 as useQueryClient } from './_tsup-dts-rollup.cjs';
 export { QueryClientProviderProps_alias_1 as QueryClientProviderProps } from './_tsup-dts-rollup.cjs';
+export { dehydrateSettled_alias_1 as dehydrateSettled } from './_tsup-dts-rollup.cjs';
 export { useIsFetching } from './_tsup-dts-rollup.cjs';
 export { useInfiniteQuery } from './_tsup-dts-rollup.cjs';
 export { infiniteQueryOptions } from './_tsup-dts-rollup.cjs';

package/build/index.d.ts

@@ -23,10 +23,12 @@ export { useQuery } from './_tsup-dts-rollup.js';
 export { queryOptions } from './_tsup-dts-rollup.js';
 export { DefinedInitialDataOptions } from './_tsup-dts-rollup.js';
 export { UndefinedInitialDataOptions } from './_tsup-dts-rollup.js';
+export { FLIGHT_DATA_SOURCE_alias_1 as FLIGHT_DATA_SOURCE } from './_tsup-dts-rollup.js';
 export { QueryClientContext_alias_1 as QueryClientContext } from './_tsup-dts-rollup.js';
 export { QueryClientProvider_alias_1 as QueryClientProvider } from './_tsup-dts-rollup.js';
 export { useQueryClient_alias_1 as useQueryClient } from './_tsup-dts-rollup.js';
 export { QueryClientProviderProps_alias_1 as QueryClientProviderProps } from './_tsup-dts-rollup.js';
+export { dehydrateSettled_alias_1 as dehydrateSettled } from './_tsup-dts-rollup.js';
 export { useIsFetching } from './_tsup-dts-rollup.js';
 export { useInfiniteQuery } from './_tsup-dts-rollup.js';
 export { infiniteQueryOptions } from './_tsup-dts-rollup.js';

package/build/index.js

@@ -1,7 +1,8 @@
-import { noop, QueryClient as QueryClient$1, shouldThrowError, InfiniteQueryObserver, hydrate, QueryObserver, replaceEqualDeep } from '@tanstack/query-core';
+import { noop, QueryClient as QueryClient$1, hydrate, dehydrate, shouldThrowError, InfiniteQueryObserver, QueryObserver, replaceEqualDeep } from '@tanstack/query-core';
 export * from '@tanstack/query-core';
 import { createContext, useContext, onCleanup, createMemo, createOptimistic, createSignal, action, createRenderEffect, untrack, repeat, $TRACK, sharedConfig, createEffect, createProjection, runWithOwner, isPending, resolve } from 'solid-js';
-import { createComponent } from '@solidjs/web';
+import { createComponent, REVALIDATE_HEADER } from '@solidjs/web';
+import { subscribeFlightData } from '@solidjs/web/server-functions';
 
 // src/index.ts
 var QueryClient = class extends QueryClient$1 {
@@ -11,6 +12,18 @@ var QueryClient = class extends QueryClient$1 {
 };
 var isServer = typeof window === "undefined";
 var HYDRATION_KEY_PREFIX = "sq:";
+var FLIGHT_DATA_SOURCE = "sq";
+function sweepRevalidatedQueries(client, payload, response) {
+  const keys = response.headers.get(REVALIDATE_HEADER)?.split(",");
+  if (!keys) return;
+  const covered = new Set(payload.queries.map((query) => query.queryHash));
+  for (const key of keys) {
+    client.invalidateQueries({
+      queryKey: [key],
+      predicate: (query) => !covered.has(query.queryHash)
+    }).catch(() => void 0);
+  }
+}
 var QueryClientContext = createContext(null);
 var useQueryClient = (queryClient) => {
   if (queryClient) {
@@ -26,9 +39,11 @@ function serializeCacheOnServer(client) {
   const ctx = sharedConfig.context;
   if (!ctx || !ctx.async || ctx.noHydrate) return;
   const cache = client.getQueryCache();
+  const shouldDehydrateQuery = client.getDefaultOptions().dehydrate?.shouldDehydrateQuery;
   const seen = /* @__PURE__ */ new Set();
   const serializeQuery = (query) => {
     if (seen.has(query.queryHash)) return;
+    if (shouldDehydrateQuery && !shouldDehydrateQuery(query)) return;
     const state = query.state;
     if (state.status === "success") {
       seen.add(query.queryHash);
@@ -52,7 +67,18 @@ function serializeCacheOnServer(client) {
 var QueryClientProvider = (props) => {
   props.client.mount();
   onCleanup(() => props.client.unmount());
-  if (isServer) serializeCacheOnServer(props.client);
+  if (isServer) {
+    serializeCacheOnServer(props.client);
+    onCleanup(() => {
+      props.client.cancelQueries().catch(() => void 0);
+      props.client.clear();
+    });
+  } else {
+    onCleanup(subscribeFlightData(FLIGHT_DATA_SOURCE, (data, context) => {
+      hydrate(props.client, data);
+      sweepRevalidatedQueries(props.client, data, context.response);
+    }));
+  }
   return createComponent(QueryClientContext, {
     value: () => props.client,
     get children() {
@@ -431,6 +457,15 @@ function useQuery(options, queryClient) {
 function queryOptions(options) {
   return options;
 }
+async function dehydrateSettled(client, options) {
+  const cache = client.getQueryCache();
+  for (; ; ) {
+    const pending = cache.getAll().filter((query) => query.state.fetchStatus !== "idle").map((query) => query.promise);
+    if (pending.length === 0) break;
+    await Promise.allSettled(pending);
+  }
+  return dehydrate(client, options);
+}
 var isServer3 = typeof window === "undefined";
 function createCacheAggregate(subscribe, read, empty) {
   const hydratedMount = !isServer3 && sharedConfig.hydrating === true;
@@ -591,15 +626,13 @@ function useMutation(options, queryClient) {
   const [flight, setFlight] = createOptimistic(null);
   const [settled, setSettled] = createSignal(IDLE);
   let activeMutation = null;
+  let unsubscribeFlight = null;
   const [flightVersion, setFlightVersion] = createSignal(0);
-  if (!isServer4) {
-    const unsubscribe = client().getMutationCache().subscribe((event) => {
-      if ("mutation" in event && event.mutation === activeMutation) {
-        setFlightVersion((v) => v + 1);
-      }
+  if (!isServer4)
+    onCleanup(() => {
+      unsubscribeFlight?.();
+      unsubscribeFlight = null;
     });
-    onCleanup(unsubscribe);
-  }
   async function* run(variables) {
     const opts = untrack(options);
     const callbackContext = {
@@ -609,7 +642,8 @@ function useMutation(options, queryClient) {
     };
     if (!isServer4) setFlight({ variables });
     opts.onMutate?.(variables, callbackContext);
-    const mutation = client().getMutationCache().build(client(), {
+    const c = untrack(client);
+    const mutation = c.getMutationCache().build(c, {
       ...opts,
       // Options-level callbacks re-run below, inside the transaction —
       // executing them here (inside the await gap) would let their
@@ -620,6 +654,20 @@ function useMutation(options, queryClient) {
       onSettled: void 0
     });
     activeMutation = mutation;
+    if (!isServer4) {
+      unsubscribeFlight?.();
+      unsubscribeFlight = c.getMutationCache().subscribe((event) => {
+        if ("mutation" in event && event.mutation === activeMutation) {
+          setFlightVersion((v) => v + 1);
+        }
+      });
+    }
+    const settleFlight = () => {
+      if (activeMutation !== mutation) return;
+      activeMutation = null;
+      unsubscribeFlight?.();
+      unsubscribeFlight = null;
+    };
     async function* settleFailure(error) {
       try {
         if (opts.onError)
@@ -647,7 +695,7 @@ function useMutation(options, queryClient) {
           variables,
           submittedAt: mutation.state.submittedAt
         });
-      activeMutation = null;
+      settleFlight();
       throw error;
     }
     let result2;
@@ -687,7 +735,7 @@ function useMutation(options, queryClient) {
         variables,
         submittedAt: mutation.state.submittedAt
       });
-    activeMutation = null;
+    settleFlight();
     return result2;
   }
   const invoke = isServer4 ? (variables) => drain(run(variables)) : action(run);
@@ -825,4 +873,4 @@ function useQueries(queriesOptions, queryClient) {
   });
 }
 
-export { IsRestoringContext, QueryClient, QueryClientContext, QueryClientProvider, infiniteQueryOptions, mutationOptions, queryOptions, useInfiniteQuery, useIsFetching, useIsMutating, useIsRestoring, useMutation, useMutationState, useQueries, useQuery, useQueryClient };
+export { FLIGHT_DATA_SOURCE, IsRestoringContext, QueryClient, QueryClientContext, QueryClientProvider, dehydrateSettled, infiniteQueryOptions, mutationOptions, queryOptions, useInfiniteQuery, useIsFetching, useIsMutating, useIsRestoring, useMutation, useMutationState, useQueries, useQuery, useQueryClient };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/solid-query",
-  "version": "6.0.0-rc.1",
+  "version": "6.0.0-rc.3",
   "description": "Primitives for managing, caching and syncing asynchronous and remote data in Solid",
   "author": "tannerlinsley",
   "license": "MIT",
@@ -53,15 +53,16 @@
     "@babel/preset-typescript": "^7.18.6",
     "@solidjs/testing-library": "^0.8.10",
     "@solidjs/vite-plugin": "^3.0.0-next.27",
-    "@solidjs/web": "^2.0.0-rc.3",
+    "@solidjs/web": "^2.0.0-rc.6",
     "babel-preset-solid": "^2.0.0-rc.2",
     "npm-run-all2": "^5.0.0",
-    "solid-js": "^2.0.0-rc.4",
+    "solid-js": "^2.0.0-rc.6",
     "tsup-preset-solid": "^2.2.0",
     "@tanstack/query-test-utils": "0.0.0"
   },
   "peerDependencies": {
-    "solid-js": ">=2.0.0-rc.4 <3.0.0"
+    "@solidjs/web": ">=2.0.0-rc.6 <3.0.0",
+    "solid-js": ">=2.0.0-rc.6 <3.0.0"
   },
   "scripts": {
     "clean": "premove ./build ./coverage ./dist-ts",

package/src/QueryClientProvider.tsx

@@ -1,5 +1,8 @@
 import { createContext, onCleanup, sharedConfig, useContext } from 'solid-js'
-import type { Query } from '@tanstack/query-core'
+import { REVALIDATE_HEADER } from '@solidjs/web'
+import { hydrate } from '@tanstack/query-core'
+import { subscribeFlightData } from '@solidjs/web/server-functions'
+import type { DehydratedState, Query } from '@tanstack/query-core'
 import type { QueryClient } from './QueryClient'
 import type { JSX } from '@solidjs/web'
 
@@ -13,6 +16,73 @@ const isServer = typeof window === 'undefined'
  */
 export const HYDRATION_KEY_PREFIX = 'sq:'
 
+/**
+ * The query cache's single-flight source id. Mutation responses can fold
+ * fresh data for multiple caches at once (Solid's multi-source
+ * single-flight protocol); this is the slice the query cache claims — the
+ * provider subscribes its consumer under it, and server collectors
+ * register under it to produce the data:
+ *
+ * ```ts
+ * import { registerFlightDataSource } from '@solidjs/web/server-functions/server'
+ * import { FLIGHT_DATA_SOURCE, dehydrate } from '@tanstack/solid-query'
+ *
+ * registerFlightDataSource(FLIGHT_DATA_SOURCE, async (event, outcome) => {
+ *   // rebuild the data for outcome.targetUrl into a QueryClient, then
+ *   return dehydrate(queryClient)
+ * })
+ * ```
+ *
+ * The slice's payload is a `DehydratedState`; the provider consumes it
+ * with `hydrate()`, so every mounted query on those keys updates before
+ * the mutation's promise resolves — no follow-up refetches.
+ *
+ * A mutation can additionally declare its invalidation SCOPE with
+ * `X-Revalidate` keys (the `revalidate` option of Solid's `reload`/
+ * `redirect` response helpers). The payload covers the slice of that scope
+ * the server could recompute; whatever a declared key matches beyond it is
+ * swept client-side (see the consumer below). For the sweep to be
+ * delivered, the collector must contribute a slice — return the dehydrated
+ * state even when it holds no queries if `outcome.revalidateKeys` is
+ * present, rather than skipping the source.
+ */
+export const FLIGHT_DATA_SOURCE = 'sq'
+
+/**
+ * The client half of key-scoped invalidation. A mutation declares its
+ * invalidation scope with `X-Revalidate` keys; the flight payload covers
+ * the part of that scope the server's collector recomputed (typically the
+ * target page's loader graph). Whatever a declared key matches BEYOND the
+ * payload — parameterized instances only this client holds, queries no
+ * loader owns — is invalidated here: active queries refetch in the
+ * background, inactive ones are marked stale for their next mount. This
+ * mirrors how Solid Router consumes the same header for its own cache.
+ *
+ * A key matches by queryKey prefix — `revalidate: 'users'` sweeps every
+ * query whose key begins with `'users'`. Payload-covered hashes are exempt:
+ * they hydrated with fresh data a moment ago, and refetching them would
+ * spend the round trip single flight just saved.
+ */
+function sweepRevalidatedQueries(
+  client: QueryClient,
+  payload: DehydratedState,
+  response: Response,
+): void {
+  const keys = response.headers.get(REVALIDATE_HEADER)?.split(',')
+  if (!keys) return
+  const covered = new Set(payload.queries.map((query) => query.queryHash))
+  for (const key of keys) {
+    client
+      .invalidateQueries({
+        queryKey: [key],
+        predicate: (query) => !covered.has(query.queryHash),
+      })
+      // Background refetch failures surface through the queries' own error
+      // states; an unhandled rejection here would fail the mutation instead.
+      .catch(() => undefined)
+  }
+}
+
 export const QueryClientContext = createContext<(() => QueryClient) | null>(
   null,
 )
@@ -64,9 +134,18 @@ function serializeCacheOnServer(client: QueryClient): void {
   if (!ctx || !ctx.async || ctx.noHydrate) return
 
   const cache = client.getQueryCache()
+  // The standard dehydrate filter gates the wire here too, so apps keep
+  // sensitive or oversized queries out of the HTML with the same option
+  // they'd pass any other transport.
+  const shouldDehydrateQuery =
+    client.getDefaultOptions().dehydrate?.shouldDehydrateQuery
   const seen = new Set<string>()
   const serializeQuery = (query: Query<any, any, any, any>) => {
     if (seen.has(query.queryHash)) return
+    // Consulted per cache event until it passes, so a filter that rejects
+    // pending queries (e.g. the core default) still admits the settled
+    // value if it lands while the request's serialization context is live.
+    if (shouldDehydrateQuery && !shouldDehydrateQuery(query)) return
     const state = query.state
     if (state.status === 'success') {
       seen.add(query.queryHash)
@@ -97,15 +176,47 @@ function serializeCacheOnServer(client: QueryClient): void {
 /**
  * Provides the QueryClient and manages its mount lifecycle. On the server
  * it also registers the cache serializer above; on the client, hooks prime
- * the cache from their hash-keyed registry entries themselves — see
- * `useBaseQuery`.
+ * the cache from their hash-keyed registry entries themselves (see
+ * `useBaseQuery`) and the provider subscribes the cache's single-flight
+ * consumer: mutation responses carrying a `FLIGHT_DATA_SOURCE` slice (a
+ * `DehydratedState` produced by a server collector registered under the
+ * same id) hydrate this client before the mutation's promise resolves.
+ * Subscribing is inert when no server collector exists — the server just
+ * folds nothing — so it is unconditional. One consumer per source: with
+ * nested providers, the innermost mounted one owns the slice.
  */
 export const QueryClientProvider = (
   props: QueryClientProviderProps,
 ): JSX.Element => {
   props.client.mount()
   onCleanup(() => props.client.unmount())
-  if (isServer) serializeCacheOnServer(props.client)
+  if (isServer) {
+    serializeCacheOnServer(props.client)
+    // Render disposal ends the request: abort what's still in flight and
+    // drop the cache so user-configured finite gcTime timers can't pin
+    // the per-request client (and whatever its queries closed over) until
+    // they fire. Serialized promises are already in seroval's hands, so
+    // clearing here can't affect the streamed payload.
+    onCleanup(() => {
+      props.client.cancelQueries().catch(() => undefined)
+      props.client.clear()
+    })
+  } else {
+    // Client-only: the server's consumer registry is module state shared
+    // across requests — registering there would leak between them.
+    onCleanup(
+      subscribeFlightData<DehydratedState>(
+        FLIGHT_DATA_SOURCE,
+        (data, context) => {
+          hydrate(props.client, data)
+          // Fresh data first, then the declared-scope sweep: stale marks
+          // land synchronously, refetches run in the background — the
+          // mutation's promise never waits on them.
+          sweepRevalidatedQueries(props.client, data, context.response)
+        },
+      ),
+    )
+  }
 
   return (
     <QueryClientContext value={() => props.client}>

package/src/dehydrateSettled.ts

@@ -0,0 +1,42 @@
+import { dehydrate } from '@tanstack/query-core'
+import type { DehydrateOptions, DehydratedState } from '@tanstack/query-core'
+import type { QueryClient } from './QueryClient'
+
+/**
+ * Waits for every fetch the client has in flight to settle, then
+ * dehydrates. This is the extraction half of a single-flight collector:
+ * after route data functions run for the mutation's target URL, loaders
+ * commonly kick off prefetches without awaiting them — plain
+ * `dehydrate()` would snapshot those mid-fetch and ship nothing.
+ *
+ * ```ts
+ * registerFlightDataSource(FLIGHT_DATA_SOURCE, (event, outcome) =>
+ *   loadFlightTarget({
+ *     router,
+ *     event,
+ *     outcome,
+ *     collect: () => dehydrateSettled(queryClient),
+ *   }),
+ * )
+ * ```
+ *
+ * Settling is chased to quiescence — awaiting one batch of fetches can
+ * dispatch more (dependent queries keyed off a first result) — so an
+ * unconditionally self-refetching query would keep this pending; that's
+ * an app bug mirrored, not guarded.
+ */
+export async function dehydrateSettled(
+  client: QueryClient,
+  options?: DehydrateOptions,
+): Promise<DehydratedState> {
+  const cache = client.getQueryCache()
+  for (;;) {
+    const pending = cache
+      .getAll()
+      .filter((query) => query.state.fetchStatus !== 'idle')
+      .map((query) => query.promise)
+    if (pending.length === 0) break
+    await Promise.allSettled(pending)
+  }
+  return dehydrate(client, options)
+}

package/src/index.ts

@@ -39,11 +39,13 @@ export type {
   UndefinedInitialDataOptions,
 } from './queryOptions'
 export {
+  FLIGHT_DATA_SOURCE,
   QueryClientContext,
   QueryClientProvider,
   useQueryClient,
 } from './QueryClientProvider'
 export type { QueryClientProviderProps } from './QueryClientProvider'
+export { dehydrateSettled } from './dehydrateSettled'
 export { useIsFetching } from './useIsFetching'
 export { useInfiniteQuery } from './useInfiniteQuery'
 export { infiniteQueryOptions } from './infiniteQueryOptions'

package/src/useMutation.ts

@@ -114,20 +114,20 @@ export function useMutation<
    * Flight metadata (retry failures, offline pause) lives on the Mutation
    * instance and changes during the await gap; a version bump per cache
    * event for the active mutation keeps reads current without cloning
-   * observer results.
+   * observer results. The subscription is per-flight, created in `run`
+   * against the same client the mutation is built on: nothing reactive is
+   * read at setup (no client read to untrack), the listener and the
+   * mutation can never sit on different clients, and an idle hook holds no
+   * cache subscription at all.
    */
   let activeMutation: Mutation<TData, TError, TVariables> | null = null
+  let unsubscribeFlight: (() => void) | null = null
   const [flightVersion, setFlightVersion] = createSignal(0)
-  if (!isServer) {
-    const unsubscribe = client()
-      .getMutationCache()
-      .subscribe((event) => {
-        if ('mutation' in event && event.mutation === activeMutation) {
-          setFlightVersion((v) => v + 1)
-        }
-      })
-    onCleanup(unsubscribe)
-  }
+  if (!isServer)
+    onCleanup(() => {
+      unsubscribeFlight?.()
+      unsubscribeFlight = null
+    })
 
   async function* run(
     variables: TVariables,
@@ -144,19 +144,33 @@ export function useMutation<
     if (!isServer) setFlight({ variables })
     opts.onMutate?.(variables, callbackContext)
 
-    const mutation = client()
-      .getMutationCache()
-      .build(client(), {
-        ...opts,
-        // Options-level callbacks re-run below, inside the transaction —
-        // executing them here (inside the await gap) would let their
-        // cache writes and invalidations escape the atomic settle.
-        onMutate: undefined,
-        onSuccess: undefined,
-        onError: undefined,
-        onSettled: undefined,
-      }) as unknown as Mutation<TData, TError, TVariables>
+    const c = untrack(client)
+    const mutation = c.getMutationCache().build(c, {
+      ...opts,
+      // Options-level callbacks re-run below, inside the transaction —
+      // executing them here (inside the await gap) would let their
+      // cache writes and invalidations escape the atomic settle.
+      onMutate: undefined,
+      onSuccess: undefined,
+      onError: undefined,
+      onSettled: undefined,
+    }) as unknown as Mutation<TData, TError, TVariables>
     activeMutation = mutation
+    if (!isServer) {
+      // A rapid re-mutate replaces the previous flight's listener.
+      unsubscribeFlight?.()
+      unsubscribeFlight = c.getMutationCache().subscribe((event) => {
+        if ('mutation' in event && event.mutation === activeMutation) {
+          setFlightVersion((v) => v + 1)
+        }
+      })
+    }
+    const settleFlight = () => {
+      if (activeMutation !== mutation) return
+      activeMutation = null
+      unsubscribeFlight?.()
+      unsubscribeFlight = null
+    }
 
     /**
      * Failure settle, shared by both paths. Callback routing mirrors
@@ -202,7 +216,7 @@ export function useMutation<
           variables,
           submittedAt: mutation.state.submittedAt,
         })
-      activeMutation = null
+      settleFlight()
       throw error
     }
 
@@ -250,7 +264,7 @@ export function useMutation<
         variables,
         submittedAt: mutation.state.submittedAt,
       })
-    activeMutation = null
+    settleFlight()
     return result
   }