@raf-query/react 0.1.15 → 0.1.17

package/CHANGELOG.md

@@ -1,8 +1,20 @@
 # Changelog
 
+## [0.1.17](https://github.com/KATT/raf-query/compare/0.1.16...0.1.17) (2026-10-13)
+
+### Performance Improvements
+
+* **react:** browser build of the TanStack Router integration ([#48](https://github.com/KATT/raf-query/issues/48)) ([75e78cf](https://github.com/KATT/raf-query/commit/75e78cf968c069188a2688ad3298fb4bee2e3b8c))
+
+## [0.1.16](https://github.com/KATT/raf-query/compare/0.1.15...0.1.16) (2026-10-13)
+
+### Bug Fixes
+
+- stale data always refreshes when switching pages ([#49](https://github.com/KATT/raf-query/issues/49)) ([68652cd](https://github.com/KATT/raf-query/commit/68652cdf6ea06ef86d277329098ee294dba98f21))
+
 ## [0.1.15](https://github.com/KATT/raf-query/compare/0.1.14...0.1.15) (2026-10-13)
 
-* **tooling:** list a fixture app's modules by size ([#45](https://github.com/KATT/raf-query/issues/45)) ([0e1f899](https://github.com/KATT/raf-query/commit/0e1f899f2fecc1368f9be71a2c78e3efd2f3783b))
+- **tooling:** list a fixture app's modules by size ([#45](https://github.com/KATT/raf-query/issues/45)) ([0e1f899](https://github.com/KATT/raf-query/commit/0e1f899f2fecc1368f9be71a2c78e3efd2f3783b))
 
 ## [0.1.14](https://github.com/KATT/raf-query/compare/0.1.13...0.1.14) (2026-10-13)
 

package/README.md

@@ -161,7 +161,8 @@ return { org: qc.prefetch(orgQuery, { orgId: user.orgId }) };
 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.
+- `ensure` and `fetch` wait only on a cache miss. With stale cached data they resolve immediately, so the navigation isn't held up, and revalidate in the background: the page renders the cached data and re-renders when the refetch lands.
+- Loaders run on every navigation (TanStack Router reruns them when its own `staleTime` has passed, `0` by default), so returning to a page shows what's cached at once and then fresh data. With `defaultPreload: "intent"`, also set `defaultPreloadStaleTime: 0`: otherwise the router reuses a hover's preload for 30 seconds instead of running the loader on click, and the query cache never hears about the navigation.
 - 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.
@@ -241,7 +242,7 @@ function PostPage() {
 
 When the cache updates — refetch, invalidation, `setData` — the hook returns a new, pre-resolved promise and the component re-renders without suspending. New data is structurally shared with the old: objects and arrays that are deeply equal keep their identity, and a refetch that returns equal data keeps the same promise, so nothing re-renders. Controls are tracked: reading `controls.isFetching` subscribes the component to `isFetching`, and a change to a control it never read doesn't re-render it. When the **first** load fails, the promise rejects and `use()` throws to the nearest error boundary. Resetting that boundary refetches the query.
 
-Queries do not refetch on mount. They refetch when a loader starts them again, when invalidated, on window focus or reconnect while stale, on `refetch()`, or on `refetchInterval`.
+`useQuery` never refetches on mount: whatever started the query decides. Stale data refetches in the background when a loader or server component starts the query again (`prefetch`, `ensure`, `fetch`, or hydrating the server's copy), when `useWaterfall` mounts, when invalidated, on window focus or reconnect, on `refetch()`, or on `refetchInterval`.
 
 For an app-wide indicator, `useIsFetching()` returns how many queries have a request in flight, background refetches included, and re-renders when that changes. Pass a filter to count only some: `useIsFetching({ queryKey: ["comments"] })`. It's `0` on the server and during hydration, so the indicator never appears in server HTML. Outside React, `qc.isFetching(filter?)` returns the same number.
 
@@ -430,6 +431,8 @@ function PostAuthor(props: { post: Post }) {
 }
 ```
 
+Like `prefetch` in a loader, `useWaterfall` refetches stale cached data in the background, once each time the component mounts or its input changes. Re-renders don't refetch.
+
 The name is the warning: each waterfall is an extra round trip after render. First try to get the input from route params so the loader can start it, or have the backend return it with its parent.
 
 During SSR the `queryFn` runs on the server. TanStack Start server functions work there. Next.js rejects server actions called while rendering, so in Next.js start the dependent query in the server component instead:
@@ -567,7 +570,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.
+- `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. The browser takes the server's data when it's newer than its own. Otherwise it keeps its copy and refetches it if stale. That covers a payload the router replays from its cache (back and forward) and a `prefetch` still pending on the server.
 - `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 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.

package/dist/tanstack-router-browser.d.mts

@@ -0,0 +1,11 @@
+import { RouterIntegrationOptions } from "./tanstack-router-shared.mjs";
+import { AnyRouter } from "@tanstack/react-router";
+//#region src/tanstack-router-browser.d.ts
+/**
+ * The browser build of `@raf-query/react/tanstack-router` (the `browser`
+ * export condition): the client half only, so the server's dehydration
+ * stream stays out of the app bundle.
+ */
+export declare function setupRouterIntegration<TRouter extends AnyRouter>(options: RouterIntegrationOptions<TRouter>): void;
+//#endregion
+export type { RouterIntegrationOptions };

package/dist/tanstack-router-browser.mjs

@@ -0,0 +1,13 @@
+import { handleRedirects, setupClient } from "./tanstack-router-shared.mjs";
+//#region src/tanstack-router-browser.ts
+/**
+* The browser build of `@raf-query/react/tanstack-router` (the `browser`
+* export condition): the client half only, so the server's dehydration
+* stream stays out of the app bundle.
+*/
+function setupRouterIntegration(options) {
+	setupClient(options);
+	handleRedirects(options);
+}
+//#endregion
+export { setupRouterIntegration };

package/dist/tanstack-router-shared.d.mts

@@ -0,0 +1,13 @@
+import { QueryClient } from "./client.mjs";
+import { DehydrateOptions, DehydratedState, HydrateOptions } from "@raf-query/core";
+import { AnyRouter } from "@tanstack/react-router";
+//#region src/tanstack-router-shared.d.ts
+export interface RouterIntegrationOptions<TRouter extends AnyRouter> {
+  readonly dehydrateOptions?: DehydrateOptions;
+  /** Navigate when a `queryFn` throws `redirect()`. Default `true`. */
+  readonly handleRedirects?: boolean;
+  readonly hydrateOptions?: HydrateOptions;
+  readonly queryClient: QueryClient;
+  readonly router: TRouter;
+}
+//#endregion

package/dist/tanstack-router-shared.mjs

@@ -0,0 +1,48 @@
+import { hydrate } from "./client.mjs";
+import { Predicate } from "effect";
+import { isRedirect } from "@tanstack/react-router";
+//#region src/tanstack-router-shared.ts
+function hasRafQueries(value) {
+	return Predicate.hasProperty(value, "raf") && Predicate.isObject(value.raf);
+}
+/**
+* Hydrate each state as the server's stream delivers it. Reads the stream
+* directly: `Stream.fromReadableStream` + `QueryCache.hydrateStream` would
+* put Effect's `Stream` and `Queue` in the browser bundle.
+*/
+async function hydrateEach(client, stream, options) {
+	const reader = stream.getReader();
+	for (;;) {
+		const next = await reader.read();
+		if (next.done) return;
+		hydrate(client, next.value, options);
+	}
+}
+function setupClient(options) {
+	const router = options.router;
+	const client = options.queryClient;
+	const hydrateOptions = options.hydrateOptions;
+	const originalHydrate = router.options.hydrate;
+	router.options.hydrate = async (dehydrated) => {
+		await originalHydrate?.(dehydrated);
+		if (!hasRafQueries(dehydrated)) return;
+		const raf = dehydrated.raf;
+		hydrate(client, raf.initial, hydrateOptions);
+		hydrateEach(client, raf.stream, hydrateOptions).catch((error) => {
+			console.error("raf-query: reading the query stream failed", error);
+		});
+	};
+}
+function handleRedirects(options) {
+	if (!(options.handleRedirects ?? true)) return;
+	const router = options.router;
+	options.queryClient.subscribe((event) => {
+		if (event.type === "failed" && isRedirect(event.error)) {
+			const redirect = event.error;
+			redirect.options._fromLocation = router.stores.location.get();
+			router.navigate(router.resolveRedirect(redirect).options);
+		}
+	});
+}
+//#endregion
+export { handleRedirects, setupClient };

package/dist/tanstack-router.d.mts

@@ -1,15 +1,6 @@
-import { QueryClient } from "./client.mjs";
-import { DehydrateOptions, HydrateOptions } from "@raf-query/core";
+import { RouterIntegrationOptions } from "./tanstack-router-shared.mjs";
 import { AnyRouter } from "@tanstack/react-router";
 //#region src/tanstack-router.d.ts
-export interface RouterIntegrationOptions<TRouter extends AnyRouter> {
-  readonly dehydrateOptions?: DehydrateOptions;
-  /** Navigate when a `queryFn` throws `redirect()`. Default `true`. */
-  readonly handleRedirects?: boolean;
-  readonly hydrateOptions?: HydrateOptions;
-  readonly queryClient: QueryClient;
-  readonly router: TRouter;
-}
 /**
  * Connects a query client to a TanStack Router (and TanStack Start) router:
  *
@@ -22,4 +13,5 @@ export interface RouterIntegrationOptions<TRouter extends AnyRouter> {
  * Call it in `getRouter`, which runs once per request on the server.
  */
 export declare function setupRouterIntegration<TRouter extends AnyRouter>(options: RouterIntegrationOptions<TRouter>): void;
-//#endregion
+//#endregion
+export type { RouterIntegrationOptions };

package/dist/tanstack-router.mjs

@@ -1,5 +1,5 @@
-import { Effect, Exit, Predicate, Scope, Stream } from "effect";
-import { isRedirect } from "@tanstack/react-router";
+import { handleRedirects, setupClient } from "./tanstack-router-shared.mjs";
+import { Effect, Exit, Scope, Stream } from "effect";
 //#region src/tanstack-router.ts
 const noop = () => {};
 function setupServer(options) {
@@ -39,25 +39,6 @@ function setupServer(options) {
 		};
 	};
 }
-function hasRafQueries(value) {
-	return Predicate.hasProperty(value, "raf") && Predicate.isObject(value.raf);
-}
-function setupClient(options) {
-	const router = options.router;
-	const cache = options.queryClient.effect;
-	const hydrateOptions = options.hydrateOptions;
-	const originalHydrate = router.options.hydrate;
-	router.options.hydrate = async (dehydrated) => {
-		await originalHydrate?.(dehydrated);
-		if (!hasRafQueries(dehydrated)) return;
-		const raf = dehydrated.raf;
-		Effect.runSync(cache.hydrate(raf.initial, hydrateOptions));
-		Effect.runFork(cache.hydrateStream(Stream.fromReadableStream({
-			evaluate: () => raf.stream,
-			onError: (error) => error
-		}), hydrateOptions).pipe(Effect.catchCause((cause) => Effect.logError("raf-query: reading the query stream failed", cause))));
-	};
-}
 /**
 * Connects a query client to a TanStack Router (and TanStack Start) router:
 *
@@ -70,16 +51,9 @@ function setupClient(options) {
 * Call it in `getRouter`, which runs once per request on the server.
 */
 function setupRouterIntegration(options) {
-	const router = options.router;
-	if (router.isServer) setupServer(options);
+	if (options.router.isServer) setupServer(options);
 	else setupClient(options);
-	if (options.handleRedirects ?? true) options.queryClient.subscribe((event) => {
-		if (event.type === "failed" && isRedirect(event.error)) {
-			const redirect = event.error;
-			redirect.options._fromLocation = router.stores.location.get();
-			router.navigate(router.resolveRedirect(redirect).options);
-		}
-	});
+	handleRedirects(options);
 }
 //#endregion
 export { setupRouterIntegration };

package/dist/use-waterfall.d.mts

@@ -4,6 +4,8 @@ import { InputArgs, QueryFactory, QueryHandle } from "@raf-query/core";
  * Start a query during render and return its handle, for inputs only known
  * at render time (an id from a parent query's data). Each call is a request
  * waterfall: prefer starting the query in a loader or server component.
+ * Like `prefetch` in a loader, it refetches stale cached data in the
+ * background, once per mount and input.
  *
  * ```tsx
  * const author = useWaterfall(authorQuery, { id: post.authorId });

package/dist/use-waterfall.mjs

@@ -1,11 +1,20 @@
 "use client";
 import { useQueryClient } from "./provider.mjs";
 import { Query } from "@raf-query/core";
+import { useState } from "react";
 //#region src/use-waterfall.ts
 /**
+* First loads a waterfall suspended on. A suspended mount keeps no state, so
+* this is how its retry knows the data it finds is the load it just waited
+* for, not cached data to revalidate.
+*/
+const waitedFor = /* @__PURE__ */ new WeakSet();
+/**
 * Start a query during render and return its handle, for inputs only known
 * at render time (an id from a parent query's data). Each call is a request
 * waterfall: prefer starting the query in a loader or server component.
+* Like `prefetch` in a loader, it refetches stale cached data in the
+* background, once per mount and input.
 *
 * ```tsx
 * const author = useWaterfall(authorQuery, { id: post.authorId });
@@ -14,7 +23,13 @@ import { Query } from "@raf-query/core";
 */
 function useWaterfall(factory, ...args) {
 	const query = useQueryClient().getQuery(factory, ...args);
-	Query.readUnsafe(query);
+	const promise = Query.readUnsafe(query);
+	const [started, setStarted] = useState();
+	if (started !== query.hash) {
+		if (!Query.getUnsafe(query).hasData) waitedFor.add(promise);
+		else if (!waitedFor.delete(promise)) Query.revalidateUnsafe(query);
+		setStarted(query.hash);
+	} else if (Query.getUnsafe(query).hasData) waitedFor.delete(promise);
 	return query.handle;
 }
 //#endregion

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@raf-query/react",
-  "version": "0.1.15",
+  "version": "0.1.17",
   "description": "React bindings for raf-query, a render-as-you-fetch query library",
   "keywords": [
     "query",
@@ -37,10 +37,18 @@
     "./devtools/production": "./dist/devtools-production.mjs",
     "./next": "./dist/next.mjs",
     "./rsc": "./dist/rsc.mjs",
-    "./tanstack-router": "./dist/tanstack-router.mjs"
+    "./tanstack-router": {
+      "workerd": "./dist/tanstack-router.mjs",
+      "worker": "./dist/tanstack-router.mjs",
+      "node": "./dist/tanstack-router.mjs",
+      "deno": "./dist/tanstack-router.mjs",
+      "bun": "./dist/tanstack-router.mjs",
+      "browser": "./dist/tanstack-router-browser.mjs",
+      "default": "./dist/tanstack-router.mjs"
+    }
   },
   "dependencies": {
-    "@raf-query/core": "0.1.15"
+    "@raf-query/core": "0.1.17"
   },
   "peerDependencies": {
     "@tanstack/react-router": "^1.170.0",