@raf-query/core 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/cache.mjs

@@ -3,7 +3,7 @@ import { Platform } from "./platform.mjs";
 import { unsafeCast } from "./cast.mjs";
 import { listen } from "./listen.mjs";
 import { hashKey, matchesKey } from "./key.mjs";
-import { changes, emit, fetch, invalidate, isObserved, isStaleUnsafe, make as make$1, onPlatformEvent, provide, remove, reset, setData, setOptions, start } from "./entry.mjs";
+import { changes, emit, fetch, invalidate, isObserved, make as make$1, onPlatformEvent, provide, remove, reset, revalidate, setData, setOptions, start } from "./entry.mjs";
 import { dehydrateEntries, dehydrateStream, hydrateEntries } from "./hydration.mjs";
 import { optionsFor } from "./options.mjs";
 import { Clock, Context, Effect, Layer, Option, Predicate, RcRef, Stream } from "effect";
@@ -55,18 +55,8 @@ function keyMatcher(filter) {
 	return (entry) => matchesKey(entry.key, prefix);
 }
 /**
-* Background refetch of cached data a verb reuses. A server cache renders
-* once, so a refetch there could only duplicate a request whose result is
-* never shown; it refetches only what `invalidate` marked.
-*/
-function revalidate(entry) {
-	const state = entry.state;
-	const wanted = entry.cache.isServer ? state.isInvalidated : isStaleUnsafe(entry);
-	if (!state.isFetching && wanted) start(entry);
-}
-/**
 * Waits for an entry's data on a cache miss. Cached data returns at once,
-* and revalidates in the background (see `revalidate`).
+* and revalidates in the background (see `Entry.revalidate`).
 */
 function load(entry, pages) {
 	if (!entry.state.hasData) return unsafeCast(fetch(entry, { pages }));

package/dist/entry.d.mts

@@ -6,7 +6,7 @@ import { Pending, Thenable } from "./thenable.mjs";
 import { FetchRequest, Query, State, SubscribeOptions } from "./query.mjs";
 import { Cause, Clock, Context, Deferred, Effect, Scope, Stream } from "effect";
 declare namespace entry_d_exports {
-  export { CacheState, CancelledError, Entry, TypeId, changes, emit, entryOf, fetch, hasNextPageUnsafe, hasPreviousPageUnsafe, invalidate, isObserved, isQuery, isStaleUnsafe, make, metaOf, now, onPlatformEvent, provide, readUnsafe, remove, reset, resume, setData, setOptions, start, subscribeUnsafe };
+  export { CacheState, CancelledError, Entry, TypeId, changes, emit, entryOf, fetch, hasNextPageUnsafe, hasPreviousPageUnsafe, invalidate, isObserved, isQuery, isStaleUnsafe, make, metaOf, now, onPlatformEvent, provide, readUnsafe, remove, reset, resume, revalidate, setData, setOptions, start, subscribeUnsafe };
 }
 export declare const TypeId = "~@raf-query/core/Query";
 declare const CancelledError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => Cause.YieldableError & {
@@ -111,6 +111,12 @@ export declare function setOptions(entry: Entry, options: AnyQueryOptions, input
 export declare function readUnsafe(entry: Entry): Thenable<unknown>;
 /** Start a request unless one is in flight, without waiting for it. */
 export declare function start(entry: Entry): void;
+/**
+ * Background refetch of cached data that was asked for again. A server cache
+ * renders once, so a refetch there could only duplicate a request whose
+ * result is never shown; it refetches only what `invalidate` marked.
+ */
+export declare function revalidate(entry: Entry): void;
 export declare function fetch(entry: Entry, request?: FetchRequest): Effect.Effect<unknown, unknown>;
 export declare function invalidate(entry: Entry): Effect.Effect<void>;
 export declare function reset(entry: Entry): Effect.Effect<void>;

package/dist/entry.mjs

@@ -188,6 +188,16 @@ function readUnsafe(entry) {
 function start(entry) {
 	begin(entry, {});
 }
+/**
+* Background refetch of cached data that was asked for again. A server cache
+* renders once, so a refetch there could only duplicate a request whose
+* result is never shown; it refetches only what `invalidate` marked.
+*/
+function revalidate(entry) {
+	const state = entry.state;
+	if (!state.hasData || state.isFetching) return;
+	if (entry.cache.isServer ? state.isInvalidated : isStaleUnsafe(entry)) start(entry);
+}
 function fetch(entry, request = {}) {
 	return Effect.suspend(() => {
 		const inFlight = entry.inFlight;
@@ -477,4 +487,4 @@ function scheduleStale(entry) {
 	entry.tasks.fork("stale", Effect.sleep(Math.max(remaining, 0) + 1).pipe(Effect.andThen(Effect.sync(() => set(entry, {})))));
 }
 //#endregion
-export { CancelledError, TypeId, changes, emit, entryOf, fetch, hasNextPageUnsafe, hasPreviousPageUnsafe, invalidate, isObserved, isQuery, isStaleUnsafe, make, metaOf, now, onPlatformEvent, provide, readUnsafe, remove, reset, resume, setData, setOptions, start, subscribeUnsafe };
+export { CancelledError, TypeId, changes, emit, entryOf, fetch, hasNextPageUnsafe, hasPreviousPageUnsafe, invalidate, isObserved, isQuery, isStaleUnsafe, make, metaOf, now, onPlatformEvent, provide, readUnsafe, remove, reset, resume, revalidate, setData, setOptions, start, subscribeUnsafe };

package/dist/hydration.mjs

@@ -1,4 +1,4 @@
-import { resume, setData } from "./entry.mjs";
+import { resume, revalidate, setData } from "./entry.mjs";
 import { getUnsafe, metaUnsafe } from "./query.mjs";
 import { Data, Effect, Queue, Stream } from "effect";
 //#region src/hydration.ts
@@ -100,7 +100,10 @@ const dehydrateStream = /*#__PURE__*/ Effect.fnUntraced(function* (queries, subs
 });
 /**
 * Write dehydrated entries into a cache. Existing entries only take newer
-* data; pending entries resume the sender's request.
+* data; pending entries resume the sender's request. An entry that keeps its
+* own data (the sender's is older, as in a router's cached payload, or still
+* pending) was asked for again, so it revalidates if stale, as `prefetch`
+* would.
 */
 function hydrateEntries(entryFor, state, options) {
 	const deserialize = options.deserializeData ?? identity;
@@ -110,7 +113,9 @@ function hydrateEntries(entryFor, state, options) {
 		const current = entry.state;
 		if (query.updatedAt > 0) {
 			if (!current.hasData || current.updatedAt < query.updatedAt) setData(entry, deserialize(query.data), query.updatedAt);
+			else revalidate(entry);
 		} else if (query.promise && !current.hasData) resume(entry, Promise.resolve(query.promise).then(deserialize));
+		else revalidate(entry);
 	}
 }
 //#endregion

package/dist/query.d.mts

@@ -5,7 +5,7 @@ import { CancelledError as CancelledError$1, TypeId as TypeId$1, entry_d_exports
 import { Direction } from "./infinite.mjs";
 import { Effect, Pipeable, Stream } from "effect";
 declare namespace query_d_exports {
-  export { CancelledError, FetchRequest, Of, Query, State, SubscribeOptions, TypeId, changes, fetch, fetchNextPage, fetchPreviousPage, get, getUnsafe, hasNextPageUnsafe, hasPreviousPageUnsafe, invalidate, isQuery, isStaleUnsafe, metaUnsafe, observerCountUnsafe, readUnsafe, refetch, reset, subscribeUnsafe };
+  export { CancelledError, FetchRequest, Of, Query, State, SubscribeOptions, TypeId, changes, fetch, fetchNextPage, fetchPreviousPage, get, getUnsafe, hasNextPageUnsafe, hasPreviousPageUnsafe, invalidate, isQuery, isStaleUnsafe, metaUnsafe, observerCountUnsafe, readUnsafe, refetch, reset, revalidateUnsafe, subscribeUnsafe };
 }
 export declare const TypeId: typeof TypeId$1;
 export type TypeId = typeof TypeId;
@@ -108,6 +108,12 @@ export declare function changes<TData, TFactory extends QueryFactory, TError>(se
  * has, and retries a failed first load once its error has been shown.
  */
 export declare function readUnsafe<TData, TFactory extends QueryFactory, TError>(self: Query<TData, TFactory, TError>): Thenable<TData>;
+/**
+ * Refetch cached data in the background if it's stale, as `prefetch` does
+ * (on a server cache, only if invalidated). Does nothing without data or
+ * while a request is in flight.
+ */
+export declare function revalidateUnsafe<TData, TFactory extends QueryFactory, TError>(self: Query<TData, TFactory, TError>): void;
 /** Listen for state changes. Subscribed entries count as read. */
 export declare function subscribeUnsafe<TData, TFactory extends QueryFactory, TError>(self: Query<TData, TFactory, TError>, listener: () => void, options?: SubscribeOptions): () => void;
 /** Staleness as of now; `state.isStale` is only kept current while read. */

package/dist/query.mjs

@@ -1,6 +1,6 @@
 import { __exportAll } from "./_virtual/_rolldown/runtime.mjs";
 import { unsafeCast } from "./cast.mjs";
-import { CancelledError as CancelledError$1, TypeId as TypeId$1, changes as changes$1, entryOf, fetch as fetch$1, hasNextPageUnsafe as hasNextPageUnsafe$1, hasPreviousPageUnsafe as hasPreviousPageUnsafe$1, invalidate as invalidate$1, isQuery as isQuery$1, isStaleUnsafe as isStaleUnsafe$1, metaOf, provide, readUnsafe as readUnsafe$1, reset as reset$1, subscribeUnsafe as subscribeUnsafe$1 } from "./entry.mjs";
+import { CancelledError as CancelledError$1, TypeId as TypeId$1, changes as changes$1, entryOf, fetch as fetch$1, hasNextPageUnsafe as hasNextPageUnsafe$1, hasPreviousPageUnsafe as hasPreviousPageUnsafe$1, invalidate as invalidate$1, isQuery as isQuery$1, isStaleUnsafe as isStaleUnsafe$1, metaOf, provide, readUnsafe as readUnsafe$1, reset as reset$1, revalidate, subscribeUnsafe as subscribeUnsafe$1 } from "./entry.mjs";
 import { Effect } from "effect";
 import { dual } from "effect/Function";
 //#region src/query.ts
@@ -31,6 +31,7 @@ var query_exports = /* @__PURE__ */ __exportAll({
 	readUnsafe: () => readUnsafe,
 	refetch: () => refetch,
 	reset: () => reset,
+	revalidateUnsafe: () => revalidateUnsafe,
 	subscribeUnsafe: () => subscribeUnsafe
 });
 const TypeId = TypeId$1;
@@ -105,6 +106,14 @@ function changes(self) {
 function readUnsafe(self) {
 	return unsafeCast(readUnsafe$1(entryOf(self)));
 }
+/**
+* Refetch cached data in the background if it's stale, as `prefetch` does
+* (on a server cache, only if invalidated). Does nothing without data or
+* while a request is in flight.
+*/
+function revalidateUnsafe(self) {
+	revalidate(entryOf(self));
+}
 /** Listen for state changes. Subscribed entries count as read. */
 function subscribeUnsafe(self, listener, options) {
 	return subscribeUnsafe$1(entryOf(self), listener, options);
@@ -124,4 +133,4 @@ function observerCountUnsafe(self) {
 	return entryOf(self).listeners.size;
 }
 //#endregion
-export { CancelledError, TypeId, changes, fetch, fetchNextPage, fetchPreviousPage, get, getUnsafe, hasNextPageUnsafe, hasPreviousPageUnsafe, invalidate, isQuery, isStaleUnsafe, metaUnsafe, observerCountUnsafe, query_exports, readUnsafe, refetch, reset, subscribeUnsafe };
+export { CancelledError, TypeId, changes, fetch, fetchNextPage, fetchPreviousPage, get, getUnsafe, hasNextPageUnsafe, hasPreviousPageUnsafe, invalidate, isQuery, isStaleUnsafe, metaUnsafe, observerCountUnsafe, query_exports, readUnsafe, refetch, reset, revalidateUnsafe, subscribeUnsafe };

package/package.json

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