@raf-query/core 0.0.15 → 0.0.16

package/CHANGELOG.md

@@ -1,8 +1,14 @@
 # Changelog
 
+## [0.0.16](https://github.com/KATT/raf-query/compare/0.0.15...0.0.16) (2026-10-12)
+
+### Bug Fixes
+
+* **core:** don't revalidate cached data in server verbs ([#19](https://github.com/KATT/raf-query/issues/19)) ([0ed7d9f](https://github.com/KATT/raf-query/commit/0ed7d9fefd0b70a8aa9a85c8d2c309a9fed42903))
+
 ## [0.0.15](https://github.com/KATT/raf-query/compare/0.0.14...0.0.15) (2026-10-12)
 
-* **agent-docs:** replace local ~/dev path with upstream React link ([#17](https://github.com/KATT/raf-query/issues/17)) ([79c0314](https://github.com/KATT/raf-query/commit/79c031475c3ed62ce5a07fb91d68733534e452b3))
+- **agent-docs:** replace local ~/dev path with upstream React link ([#17](https://github.com/KATT/raf-query/issues/17)) ([79c0314](https://github.com/KATT/raf-query/commit/79c031475c3ed62ce5a07fb91d68733534e452b3))
 
 ## [0.0.14](https://github.com/KATT/raf-query/compare/0.0.13...0.0.14) (2026-10-12)
 

package/README.md

@@ -113,6 +113,7 @@ Behavior:
 
 - Every verb dedupes against the cache. A fresh entry is reused; a stale entry is refetched in the background.
 - `ensure` and `fetch` wait only on a cache miss. With stale cached data they resolve immediately and revalidate in the background.
+- On the server, cached data is always reused, whatever `staleTime` says. A server client renders once, so a background refetch could only repeat a request whose result is never shown. Entries marked by `invalidate` still refetch.
 - A failed `prefetch` never throws out of the loader. The error surfaces where the data is read, and is reported to the client's `onError`.
 - A failed `ensure` or `fetch` rejects, so it reaches the route's error boundary.
 
@@ -445,7 +446,7 @@ export default async function Page(props: {
 - `getQueryClient` is scoped to one request by React's `cache()`.
 - `HydrationBoundary` sends the request client's entries to the browser cache; pending ones stream as promises. Render one in each server component that starts queries for client components. Entries already sent in this request are skipped.
 - `QueryProvider` creates the browser client, and streams queries that client components start during SSR (`useWaterfall`) into the HTML. Pass `config` for the client's options; it must be serializable.
-- Server components that only render data can `await qc.fetch(...)` anywhere; the per-request client dedupes them.
+- Server components that only render data can `await qc.fetch(...)` anywhere; the per-request client makes one request per query, whatever its `staleTime`.
 - `fetch` returns data, not a handle. When a server component renders the data and also hands the query to a client component, pass `await qc.ensure(...)`: after the `fetch` it resolves from the cache, and the client component gets the data from `useQuery` without a promise.
 - Factories can call server actions: server components call them directly, and the browser calls them on refetch. Validate their arguments, since anyone can call them.
 
@@ -540,7 +541,7 @@ Both render nothing on the server, since the server's cache isn't the browser's.
 | `getAll()`, `getQuery(factory, input?)`     | Cache entries, for devtools and integrations                                                                            |
 | `clear()`                                   | Drop every entry and abort in-flight requests                                                                           |
 | `mount()`                                   | Start window-focus and reconnect refetching. The providers call it                                                      |
-| `isServer`                                  | Detected from `window`. Server clients don't retry, never gc, skip stale timers                                         |
+| `isServer`                                  | Detected from `window`. Server clients don't retry, never gc, skip stale timers, and never revalidate cached data       |
 
 Query options, accepted by `queryOptions`, `infiniteQueryOptions` and `config.defaults`:
 

package/dist/client.d.mts

@@ -8,7 +8,9 @@ export interface QueryClientConfig {
   readonly defaults?: QueryBehavior;
   /**
    * Whether this client runs on the server. Detected from `window`. Server
-   * clients don't retry, never garbage-collect, and skip stale timers.
+   * clients don't retry, never garbage-collect, skip stale timers, and reuse
+   * cached data in `prefetch` / `ensure` / `fetch` instead of revalidating
+   * it, unless `invalidate` marked it.
    */
   readonly isServer?: boolean;
   /** Called with every failed request, including failed prefetches. */
@@ -63,14 +65,16 @@ export declare class QueryClient {
   getQuery<TFactory extends QueryFactory>(factory: TFactory, ...args: InputArgs<TFactory>): Query<DataOf<TFactory>, TFactory>;
   /**
    * Start a query without waiting and return its handle. Fresh data is
-   * reused; stale data refetches in the background. Errors surface where the
-   * data is read, never here.
+   * reused; stale data refetches in the background (in the browser only, see
+   * {@link QueryClientConfig.isServer}). Errors surface where the data is
+   * read, never here.
    */
   prefetch<TFactory extends QueryFactory>(factory: TFactory, ...args: InputArgs<TFactory>): QueryHandle<TFactory>;
   /**
    * Start a query and wait for it on a cache miss. Rejects if that request
-   * fails. Stale cached data resolves immediately and revalidates. The
-   * handle is marked `ensured`, so `useQuery` returns its data directly.
+   * fails. Stale cached data resolves immediately and revalidates in the
+   * browser. The handle is marked `ensured`, so `useQuery` returns its data
+   * directly.
    */
   ensure<TFactory extends QueryFactory>(factory: TFactory, ...args: LoadArgs<TFactory>): Promise<EnsuredQueryHandle<TFactory>>;
   /** Like `ensure`, but resolves to the data. */

package/dist/client.mjs

@@ -90,19 +90,21 @@ var QueryClient = class {
 	}
 	/**
 	* Start a query without waiting and return its handle. Fresh data is
-	* reused; stale data refetches in the background. Errors surface where the
-	* data is read, never here.
+	* reused; stale data refetches in the background (in the browser only, see
+	* {@link QueryClientConfig.isServer}). Errors surface where the data is
+	* read, never here.
 	*/
 	prefetch(factory, ...args) {
 		const entry = this.#build(factory, args[0]);
-		const state = entry.getState();
-		if (!state.isFetching && (!state.hasData || entry.isStaleNow())) entry.fetch().catch(noop);
+		if (entry.getState().hasData) this.#revalidate(entry);
+		else entry.fetch().catch(noop);
 		return handleOf(entry);
 	}
 	/**
 	* Start a query and wait for it on a cache miss. Rejects if that request
-	* fails. Stale cached data resolves immediately and revalidates. The
-	* handle is marked `ensured`, so `useQuery` returns its data directly.
+	* fails. Stale cached data resolves immediately and revalidates in the
+	* browser. The handle is marked `ensured`, so `useQuery` returns its data
+	* directly.
 	*/
 	async ensure(factory, ...args) {
 		const entry = this.#build(factory, args[0]);
@@ -199,9 +201,19 @@ var QueryClient = class {
 	#load(entry, pages) {
 		const state = entry.getState();
 		if (!state.hasData) return entry.fetch({ pages });
-		if (!state.isFetching && entry.isStaleNow()) entry.fetch().catch(noop);
+		this.#revalidate(entry);
 		return Promise.resolve(state.data);
 	}
+	/**
+	* Background refetch of cached data a verb reuses. A server client renders
+	* once, so a refetch there could only duplicate a request whose result is
+	* never shown; it refetches only what `invalidate` marked.
+	*/
+	#revalidate(entry) {
+		const state = entry.getState();
+		const wanted = this.isServer ? state.isInvalidated : entry.isStaleNow();
+		if (!state.isFetching && wanted) entry.fetch().catch(noop);
+	}
 	#match(target, input) {
 		if (Predicate.isFunction(target)) {
 			const entry = this.#cache.get(hashKey(optionsFor(target, input).queryKey));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@raf-query/core",
-  "version": "0.0.15",
+  "version": "0.0.16",
   "description": "Framework-agnostic core of raf-query, a render-as-you-fetch query library",
   "keywords": [
     "query",