@tanstack/solid-query 6.0.0-rc.2 → 6.0.0-rc.4

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

@@ -318,6 +318,14 @@ export { FetchStatus }
  * 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`/`respond` 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). The transport
+ * delivers a response carrying keys to the consumer whether or not the
+ * collector contributed a slice — with no slice, the whole scope is swept.
  */
 declare const FLIGHT_DATA_SOURCE = "sq";
 export { FLIGHT_DATA_SOURCE }

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

@@ -318,6 +318,14 @@ export { FetchStatus }
  * 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`/`respond` 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). The transport
+ * delivers a response carrying keys to the consumer whether or not the
+ * collector contributed a slice — with no slice, the whole scope is swept.
  */
 declare const FLIGHT_DATA_SOURCE = "sq";
 export { FLIGHT_DATA_SOURCE }

package/build/dev.cjs

@@ -14,6 +14,27 @@ exports.QueryClient = class QueryClient extends queryCore.QueryClient {
 var isServer = typeof window === "undefined";
 var HYDRATION_KEY_PREFIX = "sq:";
 exports.FLIGHT_DATA_SOURCE = "sq";
+var REVALIDATE_ALL = "*";
+function sweepRevalidatedQueries(client, payload, response) {
+  const declared = response.headers.get(web.REVALIDATE_HEADER);
+  if (declared === null) return;
+  const covered = new Set(payload?.queries.map((query) => query.queryHash) ?? []);
+  const uncovered = (query) => !covered.has(query.queryHash);
+  const keys = declared.split(",");
+  if (keys.includes(REVALIDATE_ALL)) {
+    client.invalidateQueries({
+      predicate: uncovered
+    }).catch(() => void 0);
+    return;
+  }
+  for (const key of keys) {
+    if (!key) continue;
+    client.invalidateQueries({
+      queryKey: [key],
+      predicate: uncovered
+    }).catch(() => void 0);
+  }
+}
 exports.QueryClientContext = solidJs.createContext(null);
 exports.useQueryClient = (queryClient) => {
   if (queryClient) {
@@ -64,8 +85,9 @@ exports.QueryClientProvider = (props) => {
       props.client.clear();
     });
   } else {
-    solidJs.onCleanup(serverFunctions.subscribeFlightData(exports.FLIGHT_DATA_SOURCE, (data) => {
+    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, {
@@ -134,6 +156,7 @@ function useBaseQueryLayer(options, Observer, queryClient) {
   let disposed = false;
   let shouldAttach = false;
   let activeClient = solidJs.untrack(client);
+  let lastQuery;
   const attach = () => {
     if (!disposed && !observerSub && !solidJs.untrack(isRestoring)) {
       shouldAttach = true;
@@ -143,6 +166,7 @@ function useBaseQueryLayer(options, Observer, queryClient) {
   const syncClient = (c) => {
     if (isServer2 || c === activeClient) return;
     activeClient = c;
+    lastQuery = void 0;
     cacheSub?.();
     cacheSub = c.getQueryCache().subscribe(onCacheEvent);
     observerSub?.();
@@ -234,7 +258,14 @@ function useBaseQueryLayer(options, Observer, queryClient) {
     version();
     const c = client();
     syncClient(c);
-    return c.getQueryCache().build(c, defaultedOptions());
+    const cache = c.getQueryCache();
+    const opts = defaultedOptions();
+    const existing = cache.get(
+      opts.queryHash
+    );
+    if (existing) return lastQuery = existing;
+    if (lastQuery?.queryHash === opts.queryHash) return lastQuery;
+    return lastQuery = cache.build(c, opts);
   };
   const isEnabled = () => {
     const opts = defaultedOptions();
@@ -293,6 +324,7 @@ function useBaseQueryLayer(options, Observer, queryClient) {
       if (!isServer2) observer.setOptions(opts);
       return chainOnce(q.fetch(opts), select, wrap);
     }
+    if (isServer2) return { value: void 0 };
     return NEVER;
   };
   const dataStore = solidJs.createProjection(

package/build/dev.js

@@ -1,7 +1,7 @@
 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
@@ -13,6 +13,27 @@ var QueryClient = class extends QueryClient$1 {
 var isServer = typeof window === "undefined";
 var HYDRATION_KEY_PREFIX = "sq:";
 var FLIGHT_DATA_SOURCE = "sq";
+var REVALIDATE_ALL = "*";
+function sweepRevalidatedQueries(client, payload, response) {
+  const declared = response.headers.get(REVALIDATE_HEADER);
+  if (declared === null) return;
+  const covered = new Set(payload?.queries.map((query) => query.queryHash) ?? []);
+  const uncovered = (query) => !covered.has(query.queryHash);
+  const keys = declared.split(",");
+  if (keys.includes(REVALIDATE_ALL)) {
+    client.invalidateQueries({
+      predicate: uncovered
+    }).catch(() => void 0);
+    return;
+  }
+  for (const key of keys) {
+    if (!key) continue;
+    client.invalidateQueries({
+      queryKey: [key],
+      predicate: uncovered
+    }).catch(() => void 0);
+  }
+}
 var QueryClientContext = createContext(null);
 var useQueryClient = (queryClient) => {
   if (queryClient) {
@@ -63,8 +84,9 @@ var QueryClientProvider = (props) => {
       props.client.clear();
     });
   } else {
-    onCleanup(subscribeFlightData(FLIGHT_DATA_SOURCE, (data) => {
+    onCleanup(subscribeFlightData(FLIGHT_DATA_SOURCE, (data, context) => {
       hydrate(props.client, data);
+      sweepRevalidatedQueries(props.client, data, context.response);
     }));
   }
   return createComponent(QueryClientContext, {
@@ -133,6 +155,7 @@ function useBaseQueryLayer(options, Observer, queryClient) {
   let disposed = false;
   let shouldAttach = false;
   let activeClient = untrack(client);
+  let lastQuery;
   const attach = () => {
     if (!disposed && !observerSub && !untrack(isRestoring)) {
       shouldAttach = true;
@@ -142,6 +165,7 @@ function useBaseQueryLayer(options, Observer, queryClient) {
   const syncClient = (c) => {
     if (isServer2 || c === activeClient) return;
     activeClient = c;
+    lastQuery = void 0;
     cacheSub?.();
     cacheSub = c.getQueryCache().subscribe(onCacheEvent);
     observerSub?.();
@@ -233,7 +257,14 @@ function useBaseQueryLayer(options, Observer, queryClient) {
     version();
     const c = client();
     syncClient(c);
-    return c.getQueryCache().build(c, defaultedOptions());
+    const cache = c.getQueryCache();
+    const opts = defaultedOptions();
+    const existing = cache.get(
+      opts.queryHash
+    );
+    if (existing) return lastQuery = existing;
+    if (lastQuery?.queryHash === opts.queryHash) return lastQuery;
+    return lastQuery = cache.build(c, opts);
   };
   const isEnabled = () => {
     const opts = defaultedOptions();
@@ -292,6 +323,7 @@ function useBaseQueryLayer(options, Observer, queryClient) {
       if (!isServer2) observer.setOptions(opts);
       return chainOnce(q.fetch(opts), select, wrap);
     }
+    if (isServer2) return { value: void 0 };
     return NEVER;
   };
   const dataStore = createProjection(

package/build/index.cjs

@@ -14,6 +14,27 @@ exports.QueryClient = class QueryClient extends queryCore.QueryClient {
 var isServer = typeof window === "undefined";
 var HYDRATION_KEY_PREFIX = "sq:";
 exports.FLIGHT_DATA_SOURCE = "sq";
+var REVALIDATE_ALL = "*";
+function sweepRevalidatedQueries(client, payload, response) {
+  const declared = response.headers.get(web.REVALIDATE_HEADER);
+  if (declared === null) return;
+  const covered = new Set(payload?.queries.map((query) => query.queryHash) ?? []);
+  const uncovered = (query) => !covered.has(query.queryHash);
+  const keys = declared.split(",");
+  if (keys.includes(REVALIDATE_ALL)) {
+    client.invalidateQueries({
+      predicate: uncovered
+    }).catch(() => void 0);
+    return;
+  }
+  for (const key of keys) {
+    if (!key) continue;
+    client.invalidateQueries({
+      queryKey: [key],
+      predicate: uncovered
+    }).catch(() => void 0);
+  }
+}
 exports.QueryClientContext = solidJs.createContext(null);
 exports.useQueryClient = (queryClient) => {
   if (queryClient) {
@@ -64,8 +85,9 @@ exports.QueryClientProvider = (props) => {
       props.client.clear();
     });
   } else {
-    solidJs.onCleanup(serverFunctions.subscribeFlightData(exports.FLIGHT_DATA_SOURCE, (data) => {
+    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, {
@@ -134,6 +156,7 @@ function useBaseQueryLayer(options, Observer, queryClient) {
   let disposed = false;
   let shouldAttach = false;
   let activeClient = solidJs.untrack(client);
+  let lastQuery;
   const attach = () => {
     if (!disposed && !observerSub && !solidJs.untrack(isRestoring)) {
       shouldAttach = true;
@@ -143,6 +166,7 @@ function useBaseQueryLayer(options, Observer, queryClient) {
   const syncClient = (c) => {
     if (isServer2 || c === activeClient) return;
     activeClient = c;
+    lastQuery = void 0;
     cacheSub?.();
     cacheSub = c.getQueryCache().subscribe(onCacheEvent);
     observerSub?.();
@@ -234,7 +258,14 @@ function useBaseQueryLayer(options, Observer, queryClient) {
     version();
     const c = client();
     syncClient(c);
-    return c.getQueryCache().build(c, defaultedOptions());
+    const cache = c.getQueryCache();
+    const opts = defaultedOptions();
+    const existing = cache.get(
+      opts.queryHash
+    );
+    if (existing) return lastQuery = existing;
+    if (lastQuery?.queryHash === opts.queryHash) return lastQuery;
+    return lastQuery = cache.build(c, opts);
   };
   const isEnabled = () => {
     const opts = defaultedOptions();
@@ -293,6 +324,7 @@ function useBaseQueryLayer(options, Observer, queryClient) {
       if (!isServer2) observer.setOptions(opts);
       return chainOnce(q.fetch(opts), select, wrap);
     }
+    if (isServer2) return { value: void 0 };
     return NEVER;
   };
   const dataStore = solidJs.createProjection(

package/build/index.js

@@ -1,7 +1,7 @@
 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
@@ -13,6 +13,27 @@ var QueryClient = class extends QueryClient$1 {
 var isServer = typeof window === "undefined";
 var HYDRATION_KEY_PREFIX = "sq:";
 var FLIGHT_DATA_SOURCE = "sq";
+var REVALIDATE_ALL = "*";
+function sweepRevalidatedQueries(client, payload, response) {
+  const declared = response.headers.get(REVALIDATE_HEADER);
+  if (declared === null) return;
+  const covered = new Set(payload?.queries.map((query) => query.queryHash) ?? []);
+  const uncovered = (query) => !covered.has(query.queryHash);
+  const keys = declared.split(",");
+  if (keys.includes(REVALIDATE_ALL)) {
+    client.invalidateQueries({
+      predicate: uncovered
+    }).catch(() => void 0);
+    return;
+  }
+  for (const key of keys) {
+    if (!key) continue;
+    client.invalidateQueries({
+      queryKey: [key],
+      predicate: uncovered
+    }).catch(() => void 0);
+  }
+}
 var QueryClientContext = createContext(null);
 var useQueryClient = (queryClient) => {
   if (queryClient) {
@@ -63,8 +84,9 @@ var QueryClientProvider = (props) => {
       props.client.clear();
     });
   } else {
-    onCleanup(subscribeFlightData(FLIGHT_DATA_SOURCE, (data) => {
+    onCleanup(subscribeFlightData(FLIGHT_DATA_SOURCE, (data, context) => {
       hydrate(props.client, data);
+      sweepRevalidatedQueries(props.client, data, context.response);
     }));
   }
   return createComponent(QueryClientContext, {
@@ -133,6 +155,7 @@ function useBaseQueryLayer(options, Observer, queryClient) {
   let disposed = false;
   let shouldAttach = false;
   let activeClient = untrack(client);
+  let lastQuery;
   const attach = () => {
     if (!disposed && !observerSub && !untrack(isRestoring)) {
       shouldAttach = true;
@@ -142,6 +165,7 @@ function useBaseQueryLayer(options, Observer, queryClient) {
   const syncClient = (c) => {
     if (isServer2 || c === activeClient) return;
     activeClient = c;
+    lastQuery = void 0;
     cacheSub?.();
     cacheSub = c.getQueryCache().subscribe(onCacheEvent);
     observerSub?.();
@@ -233,7 +257,14 @@ function useBaseQueryLayer(options, Observer, queryClient) {
     version();
     const c = client();
     syncClient(c);
-    return c.getQueryCache().build(c, defaultedOptions());
+    const cache = c.getQueryCache();
+    const opts = defaultedOptions();
+    const existing = cache.get(
+      opts.queryHash
+    );
+    if (existing) return lastQuery = existing;
+    if (lastQuery?.queryHash === opts.queryHash) return lastQuery;
+    return lastQuery = cache.build(c, opts);
   };
   const isEnabled = () => {
     const opts = defaultedOptions();
@@ -292,6 +323,7 @@ function useBaseQueryLayer(options, Observer, queryClient) {
       if (!isServer2) observer.setOptions(opts);
       return chainOnce(q.fetch(opts), select, wrap);
     }
+    if (isServer2) return { value: void 0 };
     return NEVER;
   };
   const dataStore = createProjection(

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/solid-query",
-  "version": "6.0.0-rc.2",
+  "version": "6.0.0-rc.4",
   "description": "Primitives for managing, caching and syncing asynchronous and remote data in Solid",
   "author": "tannerlinsley",
   "license": "MIT",

package/src/QueryClientProvider.tsx

@@ -1,4 +1,5 @@
 import { createContext, onCleanup, sharedConfig, useContext } from 'solid-js'
+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'
@@ -35,9 +36,79 @@ export const HYDRATION_KEY_PREFIX = 'sq:'
  * 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`/`respond` 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). The transport
+ * delivers a response carrying keys to the consumer whether or not the
+ * collector contributed a slice — with no slice, the whole scope is swept.
  */
 export const FLIGHT_DATA_SOURCE = 'sq'
 
+/**
+ * The reserved `X-Revalidate` key meaning every entry: `revalidate: '*'`
+ * on Solid's response helpers. Named so a host that keys its cache
+ * differently still reads the same spelling as "all".
+ */
+const REVALIDATE_ALL = '*'
+
+/**
+ * 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. The payload is absent
+ * when the server folded no slice for this cache (no collector registered,
+ * a redirect leaving the app) — then nothing is covered and the declared
+ * scope is swept in full.
+ *
+ * The header's three states are three scopes. Absent: the mutation
+ * declared nothing, and this cache is left as it is — the route data the
+ * router reloads is its own business, and a response helper without
+ * `revalidate` is a host-default that Solid Router reads as "everything"
+ * but the query cache does not presume. Empty (`revalidate: []`): nothing,
+ * explicitly. The reserved key `*` (`revalidate: '*'`): every query in the
+ * cache, minus what the payload covered — the way to say "all" to any
+ * host, rather than relying on one host's default.
+ */
+function sweepRevalidatedQueries(
+  client: QueryClient,
+  payload: DehydratedState | undefined,
+  response: Response,
+): void {
+  const declared = response.headers.get(REVALIDATE_HEADER)
+  if (declared === null) return
+  const covered = new Set(
+    payload?.queries.map((query) => query.queryHash) ?? [],
+  )
+  const uncovered = (query: Query) => !covered.has(query.queryHash)
+  const keys = declared.split(',')
+  // Background refetch failures surface through the queries' own error
+  // states; an unhandled rejection here would fail the mutation instead.
+  if (keys.includes(REVALIDATE_ALL)) {
+    client.invalidateQueries({ predicate: uncovered }).catch(() => undefined)
+    return
+  }
+  for (const key of keys) {
+    // An empty key is the empty declaration's spelling, not a prefix that
+    // happens to match everything.
+    if (!key) continue
+    client
+      .invalidateQueries({ queryKey: [key], predicate: uncovered })
+      .catch(() => undefined)
+  }
+}
+
 export const QueryClientContext = createContext<(() => QueryClient) | null>(
   null,
 )
@@ -160,9 +231,18 @@ export const QueryClientProvider = (
     // 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) => {
-        hydrate(props.client, data)
-      }),
+      subscribeFlightData<DehydratedState>(
+        FLIGHT_DATA_SOURCE,
+        (data, context) => {
+          // `data` is undefined for a response that carried metadata but
+          // no slice for this cache; `hydrate` ignores a non-object.
+          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)
+        },
+      ),
     )
   }
 

package/src/useBaseQuery.ts

@@ -216,6 +216,27 @@ export function useBaseQueryLayer<
    * swap re-attaches the rebuilt observer iff its predecessor was attached. */
   let shouldAttach = false
   let activeClient = untrack(client)
+  /**
+   * The entry this hook last read at its current hash, and the fallback for
+   * `query()` when the cache no longer holds that hash. Removal is the case
+   * that needs it: `removeQueries()` (or `clear()`) fires 'removed' for a
+   * hash this hook is mounted on, which bumps `version` and re-runs every
+   * derived read, and a plain `build()` there would re-create the entry the
+   * caller just removed. That resurrection is not passive, since the 'added'
+   * entry also re-points the still-live observer, whose mount-fetch policy
+   * then refetches and repopulates the key, contrary to `removeQueries`
+   * being documented to remove entries instead of refetching them.
+   *
+   * The removed instance keeps its final state, so reads hold their last
+   * value until options change or a real entry returns (`setQueryData`, a
+   * refetch, a later mount). That is what the other adapters do: a React
+   * observer keeps rendering the removed query's last result while the
+   * cache stays empty.
+   *
+   * Cleared on a client swap, below: the fallback is only meaningful for the
+   * cache it was read from.
+   */
+  let lastQuery: Query<TQueryFnData, TError, TQueryData, TQueryKey> | undefined
 
   const attach = () => {
     if (!disposed && !observerSub && !untrack(isRestoring)) {
@@ -236,6 +257,7 @@ export function useBaseQueryLayer<
   const syncClient = (c: QueryClient) => {
     if (isServer || c === activeClient) return
     activeClient = c
+    lastQuery = undefined
     cacheSub?.()
     cacheSub = c.getQueryCache().subscribe(onCacheEvent)
     observerSub?.()
@@ -365,7 +387,14 @@ export function useBaseQueryLayer<
     version()
     const c = client()
     syncClient(c)
-    return c.getQueryCache().build(c, defaultedOptions() as any) as any
+    const cache = c.getQueryCache()
+    const opts = defaultedOptions()
+    const existing = cache.get<TQueryFnData, TError, TQueryData, TQueryKey>(
+      opts.queryHash,
+    )
+    if (existing) return (lastQuery = existing)
+    if (lastQuery?.queryHash === opts.queryHash) return lastQuery
+    return (lastQuery = cache.build(c, opts as any) as any)
   }
 
   const isEnabled = () => {
@@ -531,6 +560,18 @@ export function useBaseQueryLayer<
       if (!isServer) observer.setOptions(opts as any)
       return chainOnce(q.fetch(opts as any), select, wrap)
     }
+    /**
+     * Disabled, with nothing cached. The three guards above are all
+     * unreachable on the server, but this one is not, and parking here has
+     * no server meaning: the render has to finish, and nothing will enable
+     * the query or write the cache before it does. So commit the idle
+     * value — 'pending' with no data IS a disabled query's settled SSR
+     * truth, which is the contract `serverMeta` already honors by not
+     * tying its read to this node while disabled, and it is the state the
+     * client hydrates to. Committed rather than passed through `wrap`:
+     * `select` must not be invoked on absent data.
+     */
+    if (isServer) return { value: undefined as TData }
     return NEVER
   }