@raf-query/react 0.3.0 → 0.4.0

package/CHANGELOG.md

@@ -1,14 +1,28 @@
 # Changelog
 
+## [0.4.0](https://github.com/KATT/raf-query/compare/0.3.1...0.4.0) (2026-10-13)
+
+### ⚠ BREAKING CHANGES
+
+* **core:** fetch waits for stale data, as TanStack's fetchQuery does ([#63](https://github.com/KATT/raf-query/issues/63))
+
+### Bug Fixes
+
+* **core:** fetch waits for stale data, as TanStack's fetchQuery does ([#63](https://github.com/KATT/raf-query/issues/63)) ([c9785d5](https://github.com/KATT/raf-query/commit/c9785d5e99c0578c1748de3330823cc0e65f2378))
+
+## [0.3.1](https://github.com/KATT/raf-query/compare/0.3.0...0.3.1) (2026-10-13)
+
+- teach avoiding dependent queries; frame prefetch vs ensure as loading UX ([#62](https://github.com/KATT/raf-query/issues/62)) ([ec62760](https://github.com/KATT/raf-query/commit/ec627609cbbee9fa4ff0cf568f69964341e27daa))
+
 ## [0.3.0](https://github.com/KATT/raf-query/compare/0.2.8...0.3.0) (2026-10-13)
 
 ### ⚠ BREAKING CHANGES
 
-* RSC apps hydrate only through HydrationBoundary; QueryProvider moves to /rsc ([#61](https://github.com/KATT/raf-query/issues/61))
+- RSC apps hydrate only through HydrationBoundary; QueryProvider moves to /rsc ([#61](https://github.com/KATT/raf-query/issues/61))
 
 ### Features
 
-* RSC apps hydrate only through HydrationBoundary; QueryProvider moves to /rsc ([#61](https://github.com/KATT/raf-query/issues/61)) ([772de79](https://github.com/KATT/raf-query/commit/772de796adfdf267a9184fd75624ff30ae53f4fc)), references [#59](https://github.com/KATT/raf-query/issues/59) [#59](https://github.com/KATT/raf-query/issues/59) [#59](https://github.com/KATT/raf-query/issues/59) [#59](https://github.com/KATT/raf-query/issues/59)
+- RSC apps hydrate only through HydrationBoundary; QueryProvider moves to /rsc ([#61](https://github.com/KATT/raf-query/issues/61)) ([772de79](https://github.com/KATT/raf-query/commit/772de796adfdf267a9184fd75624ff30ae53f4fc)), references [#59](https://github.com/KATT/raf-query/issues/59) [#59](https://github.com/KATT/raf-query/issues/59) [#59](https://github.com/KATT/raf-query/issues/59) [#59](https://github.com/KATT/raf-query/issues/59)
 
 ## [0.2.8](https://github.com/KATT/raf-query/compare/0.2.7...0.2.8) (2026-10-13)
 

package/README.md

@@ -120,11 +120,21 @@ declare module "@raf-query/react" {
 
 All three verbs live on the query client and accept a factory plus its input.
 
-| Call                              | Returns                       | Blocks? | Use for                                                                |
-| --------------------------------- | ----------------------------- | ------- | ---------------------------------------------------------------------- |
-| `qc.prefetch(factory, input)`     | `QueryHandle`                 | No      | Data the route can render without; it streams in                       |
-| `await qc.ensure(factory, input)` | `Promise<EnsuredQueryHandle>` | Yes     | Data the route must not render without; `useQuery` returns it directly |
-| `await qc.fetch(factory, input)`  | `Promise<Data>`               | Yes     | Rendering in a server component, or building another input             |
+| Call                              | Returns                       | Use for                                                                |
+| --------------------------------- | ----------------------------- | ---------------------------------------------------------------------- |
+| `qc.prefetch(factory, input)`     | `QueryHandle`                 | Data the route can render without; it streams in                       |
+| `await qc.ensure(factory, input)` | `Promise<EnsuredQueryHandle>` | Data the route must not render without; `useQuery` returns it directly |
+| `await qc.fetch(factory, input)`  | `Promise<Data>`               | Rendering data in a server component                                   |
+
+They differ in what they wait for:
+
+| Verb       | Cache miss            | Stale data                                    | Fresh data       | TanStack Query                                 |
+| ---------- | --------------------- | --------------------------------------------- | ---------------- | ---------------------------------------------- |
+| `prefetch` | Starts the request    | Refetches in the background                   | Reused           | `prefetchQuery`, not awaited                   |
+| `ensure`   | Waits for the request | Resolves at once, refetches in the background | Resolves at once | `ensureQueryData({ revalidateIfStale: true })` |
+| `fetch`    | Waits for the request | Waits for the refetch                         | Resolves at once | `fetchQuery`                                   |
+
+So `prefetch` never holds anything up, `ensure` holds up only the first visit (returning to a page shows the cached data at once, then fresh data), and `fetch` always returns fresh data, at the cost of a round trip whenever the cache is stale. On the server, data counts as stale only once `invalidate` has marked it (see below).
 
 ```tsx
 // TanStack Start
@@ -139,6 +149,13 @@ export const Route = createFileRoute("/posts/$slug")({
 });
 ```
 
+`prefetch` and `ensure` start the request at the same moment, so neither is faster. They differ in what the user sees while it's in flight:
+
+- **`prefetch`: granular skeletons.** The navigation commits right away. Each part of the page that reads a query still loading suspends to its nearest Suspense boundary and fills in when its data streams in.
+- **`ensure`: a blocked navigation.** The previous page stays on screen until the data is in. In TanStack Router, a route with a `pendingComponent` shows it once `pendingMs` (1 second by default) has passed, which makes a full-page skeleton.
+
+Choose per query. `ensure` what the page can't lay out without, where a skeleton would only flash or shift (the post itself), and `prefetch` the rest (comments, sidebars, counts). Start every query before awaiting any of them, as the `prefetch` before the `await` above does, so a blocking query never delays the others.
+
 Await independent blocking queries together with `allKeyed`, which ships with raf-query. It's a ponyfill of the TC39 `Promise.allKeyed` proposal: a record of promises in, a promise of the same record out, rejecting on the first failure.
 
 ```ts
@@ -150,17 +167,78 @@ return await allKeyed({
 });
 ```
 
-Dependent inputs use `fetch`:
+### Avoid dependent queries
+
+A query whose input comes from another query's result can't start until that one has finished. That's a waterfall: one extra round trip per level, on every navigation. Fix it where the data is shaped, so every query a route needs starts from what the URL already holds:
+
+- **Put the input in the route.** If the page is about an organization, its id belongs in the path (`/orgs/$orgId`), not in a lookup on the current user.
+- **Have the backend resolve it.** The server already knows the session and the relations, so an endpoint can return the child with its parent, or be keyed by what the client has (`GET /me/org` instead of `GET /me` then `GET /orgs/:id`).
+
+<details>
+<summary>Example: the current user's organization</summary>
+
+A settings page needs the user and their organization, and the organization's id is a field of the user:
+
+```ts
+export const Route = createFileRoute("/settings")({
+	loader: async (args) => {
+		const qc = args.context.queryClient;
+		const user = await qc.fetch(currentUserQuery);
+		return {
+			user: qc.prefetch(currentUserQuery),
+			org: qc.prefetch(orgQuery, { orgId: user.orgId }),
+		};
+	},
+});
+```
+
+With a 150 ms round trip, the organization can't arrive before 300 ms, and the navigation is blocked for the first 150 even though nothing on the page needed the user that early. Each query keyed by the organization (members, billing) would add another 150.
+
+Fix it in the backend: the server can find the session's organization itself, so give it an endpoint and a query with no input.
+
+```ts
+export function currentOrgQuery() {
+	return queryOptions({
+		queryKey: ["org", "current"],
+		queryFn: () => getCurrentOrg(),
+	});
+}
+
+export const Route = createFileRoute("/settings")({
+	loader: (args) => {
+		const qc = args.context.queryClient;
+		return {
+			user: qc.prefetch(currentUserQuery),
+			org: qc.prefetch(currentOrgQuery),
+		};
+	},
+});
+```
+
+Or fix it in the routes: links into the page come from places that already know the organization (the org switcher, a list of orgs), so they can put its id in the URL.
 
 ```ts
-const user = await qc.fetch(currentUserQuery);
-return { org: qc.prefetch(orgQuery, { orgId: user.orgId }) };
+export const Route = createFileRoute("/orgs/$orgId/settings")({
+	loader: (args) => {
+		const qc = args.context.queryClient;
+		return {
+			user: qc.prefetch(currentUserQuery),
+			org: qc.prefetch(orgQuery, { orgId: args.params.orgId }),
+		};
+	},
+});
 ```
 
+Either way, both requests start together, and the page is ready after one round trip instead of two. Nothing waits, so each query can be a `prefetch` or an `ensure` purely for the loading experience you want.
+
+</details>
+
+When the data really can't be reshaped (a third-party API you don't control), the loader can `await qc.fetch(...)` the parent and build the input from its data, or a component can start the child with [`useWaterfall`](#render-time-inputs-usewaterfall). Both pay the extra round trip; the loader blocks the navigation on it, the component lets the rest of the page render first.
+
 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, 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.
+- Every verb dedupes against the cache: a request already in flight for the entry is joined, not repeated.
+- A stale `ensure` doesn't hold up the navigation: the page renders the cached data and re-renders when the background refetch lands. A stale `fetch` in a loader would, so loaders use `ensure`.
 - 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`.
@@ -241,7 +319,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.
 
-`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`.
+`useQuery` never refetches on mount: whatever started the query decides. Stale data refetches 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.
 

package/dist/client.d.mts

@@ -41,7 +41,11 @@ export declare class QueryClient<TServices = never> {
    * directly.
    */
   ensure<TFactory extends QueryFactory<TServices>>(factory: TFactory, ...args: QueryCache.LoadArgs<TFactory>): Promise<EnsuredQueryHandle<TFactory>>;
-  /** Like `ensure`, but resolves to the data. */
+  /**
+   * Start a query and resolve to its data. Waits on a cache miss and on
+   * stale data (on the server, only invalidated data), so the data is fresh.
+   * Rejects if that request fails.
+   */
   fetch<TFactory extends QueryFactory<TServices>>(factory: TFactory, ...args: QueryCache.LoadArgs<TFactory>): Promise<DataOf<TFactory>>;
   /**
    * Mark queries stale and refetch the ones being read. Resolves once those

package/dist/client.mjs

@@ -69,7 +69,11 @@ var QueryClient = class {
 	ensure(factory, ...args) {
 		return runLoad(provided(this.effect.ensure(factory, ...args)));
 	}
-	/** Like `ensure`, but resolves to the data. */
+	/**
+	* Start a query and resolve to its data. Waits on a cache miss and on
+	* stale data (on the server, only invalidated data), so the data is fresh.
+	* Rejects if that request fails.
+	*/
 	fetch(factory, ...args) {
 		return runLoad(provided(this.effect.fetch(factory, ...args)));
 	}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@raf-query/react",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "React bindings for raf-query, a render-as-you-fetch query library",
   "keywords": [
     "query",
@@ -47,7 +47,7 @@
     }
   },
   "dependencies": {
-    "@raf-query/core": "0.3.0"
+    "@raf-query/core": "0.4.0"
   },
   "peerDependencies": {
     "@tanstack/react-router": "^1.170.0",