@raf-query/core 0.0.15 → 0.0.17

package/CHANGELOG.md

@@ -1,8 +1,20 @@
 # Changelog
 
+## [0.0.17](https://github.com/KATT/raf-query/compare/0.0.16...0.0.17) (2026-10-12)
+
+### Features
+
+* **core:** pause retries while the browser is offline ([#18](https://github.com/KATT/raf-query/issues/18)) ([a25c664](https://github.com/KATT/raf-query/commit/a25c664359fe7248cdc8d91a14d524e37b467c6c))
+
+## [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`:
 
@@ -555,6 +556,8 @@ Query options, accepted by `queryOptions`, `infiniteQueryOptions` and `config.de
 
 `infiniteQueryOptions` also takes `getPreviousPageParam` and `maxPages`.
 
+In the browser, retries pause while `navigator.onLine` is `false`: after the retry delay, the next attempt waits for the window's `online` event. The request stays fetching meanwhile, and cancelling it (`remove`, `clear`, a restart) stops the wait. The first attempt runs regardless.
+
 `@raf-query/core`:
 
 | Export                                         | Use                                                              |

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/dist/online.mjs

@@ -0,0 +1,16 @@
+import { Effect } from "effect";
+//#region src/online.ts
+function isOffline() {
+	return "window" in globalThis && "navigator" in globalThis && "onLine" in navigator && !navigator.onLine;
+}
+/**
+* Succeeds now if the browser is online, else on the window's next `online`
+* event. Interrupting it removes the listener.
+*/
+const whenOnline = Effect.suspend(() => isOffline() ? Effect.callback((resume) => {
+	const onOnline = () => resume(Effect.void);
+	window.addEventListener("online", onOnline, { once: true });
+	return Effect.sync(() => window.removeEventListener("online", onOnline));
+}) : Effect.void);
+//#endregion
+export { whenOnline };

package/dist/query.mjs

@@ -1,4 +1,5 @@
 import { scheduleNotify } from "./notify.mjs";
+import { whenOnline } from "./online.mjs";
 import { replaceEqualDeep } from "./share.mjs";
 import { fulfilled, pending } from "./thenable.mjs";
 import { Cause, Effect, Exit, Predicate, Schedule } from "effect";
@@ -382,7 +383,16 @@ var QueryEntry = class {
 		const retry = this.#behavior("retry") ?? (this.#host.isServer ? 0 : 3);
 		const countFailure = Effect.sync(() => this.#set({ failureCount: this.#state.failureCount + 1 }));
 		const counted = once.pipe(Effect.tapError(() => countFailure));
-		if (Schedule.isSchedule(retry)) return Effect.retry(counted, retry);
+		const online = this.#host.isServer ? Effect.void : whenOnline;
+		if (Schedule.isSchedule(retry)) return Effect.suspend(() => {
+			let first = true;
+			const each = Effect.suspend(() => {
+				const wait = first ? Effect.void : online;
+				first = false;
+				return wait.pipe(Effect.andThen(counted));
+			});
+			return Effect.retry(each, retry);
+		});
 		const retryDelay = this.#behavior("retryDelay");
 		const delayFor = (failureCount, error) => {
 			if (retryDelay === void 0) return Math.min(1e3 * 2 ** (failureCount - 1), 3e4);
@@ -391,7 +401,7 @@ var QueryEntry = class {
 		const attempt = counted.pipe(Effect.catch((error) => {
 			const failureCount = this.#state.failureCount;
 			if (!shouldRetry(retry, failureCount, error)) return Effect.fail(error);
-			return Effect.sleep(delayFor(failureCount, error)).pipe(Effect.andThen(Effect.suspend(() => attempt)));
+			return Effect.sleep(delayFor(failureCount, error)).pipe(Effect.andThen(online), Effect.andThen(Effect.suspend(() => attempt)));
 		}));
 		return attempt;
 	}

package/package.json

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