@raf-query/core 0.2.8 → 0.3.1

package/CHANGELOG.md

@@ -1,8 +1,22 @@
 # Changelog
 
+## [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))
+
+### 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)
+
 ## [0.2.8](https://github.com/KATT/raf-query/compare/0.2.7...0.2.8) (2026-10-13)
 
-* **codesandbox:** speed up the branch sync ([#60](https://github.com/KATT/raf-query/issues/60)) ([9099cb2](https://github.com/KATT/raf-query/commit/9099cb2ce937104d5feb8c7033233e701f412a28))
+- **codesandbox:** speed up the branch sync ([#60](https://github.com/KATT/raf-query/issues/60)) ([9099cb2](https://github.com/KATT/raf-query/commit/9099cb2ce937104d5feb8c7033233e701f412a28))
 
 ## [0.2.7](https://github.com/KATT/raf-query/compare/0.2.6...0.2.7) (2026-10-13)
 

package/README.md

@@ -32,12 +32,11 @@ The same issue tracker, built on two frameworks so the integrations can be compa
 
 `@raf-query/react` subpath entries for framework integrations and tooling:
 
-| Entry                              | Use                                                                    |
-| ---------------------------------- | ---------------------------------------------------------------------- |
-| `@raf-query/react/tanstack-router` | Streams the router's query cache to the client during SSR              |
-| `@raf-query/react/rsc`             | `HydrationBoundary` for passing server-component queries to the client |
-| `@raf-query/react/next`            | `QueryProvider` for Next.js App Router                                 |
-| `@raf-query/react/devtools`        | [Devtools](#devtools) panel for inspecting the cache in development    |
+| Entry                              | Use                                                                 |
+| ---------------------------------- | ------------------------------------------------------------------- |
+| `@raf-query/react/tanstack-router` | Streams the router's query cache to the client during SSR           |
+| `@raf-query/react/rsc`             | `QueryProvider` and `HydrationBoundary` for React Server Components |
+| `@raf-query/react/devtools`        | [Devtools](#devtools) panel for inspecting the cache in development |
 
 ## Principles
 
@@ -125,7 +124,7 @@ All three verbs live on the query client and accept a factory plus its input.
 | --------------------------------- | ----------------------------- | ------- | ---------------------------------------------------------------------- |
 | `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             |
+| `await qc.fetch(factory, input)`  | `Promise<Data>`               | Yes     | Rendering data in a server component                                   |
 
 ```tsx
 // TanStack Start
@@ -140,6 +139,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
@@ -151,13 +157,74 @@ 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
-const user = await qc.fetch(currentUserQuery);
-return { org: qc.prefetch(orgQuery, { orgId: user.orgId }) };
+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
+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.
@@ -435,7 +502,7 @@ Like `prefetch` in a loader, `useWaterfall` refetches stale cached data in the b
 
 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:
+In TanStack Start the `queryFn` runs on the server during SSR, and the router streams the result. Under the `/rsc` `QueryProvider` it starts nothing on the server: the reader's Suspense boundary renders its fallback there, and the query loads in the browser. To have it in the HTML, start the dependent query in the server component instead:
 
 ```tsx
 const post = await qc.fetch(postQuery, { slug });
@@ -518,7 +585,7 @@ export function getRouter() {
 
 `setupRouterIntegration` streams queries during SSR, clears the request's cache when the response finishes, and turns `redirect()` thrown from a `queryFn` into a router navigation. `getRouter` runs per request on the server, so each request gets its own client. Options: `dehydrateOptions` (`filter`, `keepErrors`, `serializeData`), `hydrateOptions` (`deserializeData`), and `handleRedirects: false` to handle redirects yourself. By default a server error crosses to the browser as a `RedactedError` naming the query, so its message doesn't leak into the page.
 
-### Next.js App Router
+### React Server Components (Next.js App Router)
 
 ```tsx
 // app/get-query-client.ts
@@ -530,7 +597,7 @@ export const getQueryClient = cache(() => new QueryClient());
 
 ```tsx
 // app/layout.tsx
-import { QueryProvider } from "@raf-query/react/next";
+import { QueryProvider } from "@raf-query/react/rsc";
 
 export default function RootLayout(props: { children: React.ReactNode }) {
 	return (
@@ -570,8 +637,9 @@ 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. 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.
+- `HydrationBoundary` sends the request client's entries to the browser cache; pending ones stream as promises through the RSC payload. Render one in each server component that starts queries for client components. Entries already sent in this request are skipped.
+- The browser takes whichever copy is newer, by when it was fetched (`updatedAt`, so server and browser clocks should agree). When it has no data and no request of its own, it resumes the server's pending request. When it has data, or its own request in flight, it waits for the server's instead of fetching again, and takes it if newer. If it keeps its own copy (the server's is older, as in a payload the router replays from its cache on back and forward, or the server's request failed), it refetches it if stale.
+- `QueryProvider` creates one client per server render and one per browser tab. The server render starts no request: a client component reading a query no `HydrationBoundary` sent renders its Suspense fallback on the server, and the query loads in the browser. That boundary renders in the browser through React's error recovery, with the digest Next.js uses for `ssr: false`, so Next.js doesn't report it; other frameworks pass it to `onRecoverableError`. 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.
 - 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. The browser runs a page's server actions one at a time, so refetches wait for each other and for any pending mutation. For parallel requests, have the `queryFn` call a [Route Handler](https://nextjs.org/docs/app/api-reference/file-conventions/route), as [`examples/nextjs`](examples/nextjs) does.

package/dist/entry.d.mts

@@ -122,8 +122,14 @@ export declare function invalidate(entry: Entry): Effect.Effect<void>;
 export declare function reset(entry: Entry): Effect.Effect<void>;
 /** Write data directly, as if a request had returned it. */
 export declare function setData(entry: Entry, data: unknown, updatedAt?: number): void;
-/** Adopt a request started elsewhere (the server's, during hydration). */
-export declare function resume(entry: Entry, promise: PromiseLike<unknown>): void;
+/**
+ * Adopt a request started elsewhere (the server's, during hydration). Its
+ * data counts as fetched when the sender got it, not when it arrived.
+ */
+export declare function resume(entry: Entry, promise: PromiseLike<{
+  readonly data?: unknown;
+  readonly updatedAt: number;
+}>): void;
 /** Refetch a read, stale entry whose readers want it on this event. */
 export declare function onPlatformEvent(entry: Entry, event: PlatformEvent): void;
 /** Take `entry` out of its cache: interrupt its fibers and fail its awaiters. */

package/dist/entry.mjs

@@ -235,10 +235,18 @@ function reset(entry) {
 function setData(entry, data, updatedAt = now(entry)) {
 	succeed(entry, data, updatedAt);
 }
-/** Adopt a request started elsewhere (the server's, during hydration). */
+/**
+* Adopt a request started elsewhere (the server's, during hydration). Its
+* data counts as fetched when the sender got it, not when it arrived.
+*/
 function resume(entry, promise) {
 	if (entry.state.hasData || entry.inFlight) return;
-	startRequest(entry, Effect.promise(() => Promise.resolve(promise)), void 0);
+	let updatedAt;
+	startRequest(entry, Effect.promise(async () => {
+		const result = await promise;
+		updatedAt = result.updatedAt;
+		return result.data;
+	}), void 0, () => updatedAt);
 }
 /** Refetch a read, stale entry whose readers want it on this event. */
 function onPlatformEvent(entry, event) {
@@ -293,7 +301,7 @@ function set(entry, patch) {
 	scheduleStale(entry);
 }
 /** Run `request` as the entry's request fiber, settling into its awaiter. */
-function startRequest(entry, request, direction) {
+function startRequest(entry, request, direction, updatedAt) {
 	if (!entry.inFlight) entry.failureCountBefore = entry.state.failureCount;
 	const awaiter = entry.inFlight ?? Deferred.makeUnsafe();
 	entry.inFlight = awaiter;
@@ -315,14 +323,14 @@ function startRequest(entry, request, direction) {
 		fetchDirection: direction,
 		isFetching: true
 	});
-	entry.tasks.fork("request", Effect.exit(request).pipe(Effect.flatMap((exit) => Effect.sync(() => settle(entry, awaiter, exit)))));
+	entry.tasks.fork("request", Effect.exit(request).pipe(Effect.flatMap((exit) => Effect.sync(() => settle(entry, awaiter, exit, updatedAt?.() ?? now(entry))))));
 	return awaiter;
 }
-function settle(entry, awaiter, exit) {
+function settle(entry, awaiter, exit, updatedAt) {
 	if (entry.inFlight !== awaiter) return;
 	entry.inFlight = void 0;
 	if (Exit.isSuccess(exit)) {
-		const data = succeed(entry, exit.value, now(entry));
+		const data = succeed(entry, exit.value, updatedAt);
 		Deferred.doneUnsafe(awaiter, Exit.succeed(data));
 	} else if (Cause.hasInterruptsOnly(exit.cause)) {
 		set(entry, {
@@ -366,13 +374,14 @@ function succeed(entry, next, updatedAt) {
 	entry.pending = void 0;
 	firstLoad?.resolve(data);
 	const unchanged = previous.hasData && data === previous.data;
+	const isFetching = entry.inFlight !== void 0;
 	set(entry, {
 		data,
 		error: null,
 		failureCount: 0,
-		fetchDirection: void 0,
+		fetchDirection: isFetching ? previous.fetchDirection : void 0,
 		hasData: true,
-		isFetching: false,
+		isFetching,
 		isInvalidated: false,
 		promise: firstLoad?.promise ?? (unchanged ? previous.promise : fulfilled(data)),
 		status: "success",

package/dist/hydration.d.mts

@@ -5,6 +5,12 @@ import "./entry.mjs";
 import { Query, query_d_exports } from "./query.mjs";
 import { Cause, Effect, Scope, Stream } from "effect";
 //#region src/hydration.d.ts
+/** What a dehydrated pending query's promise resolves to. */
+export interface DehydratedResult {
+  readonly data?: unknown;
+  /** When the sender got `data` (ms since epoch). */
+  readonly updatedAt: number;
+}
 /**
  * One cache entry in transit. Settled entries carry `data`; entries still
  * loading their first data carry the request's `promise`, so the receiving
@@ -15,7 +21,7 @@ export interface DehydratedQuery {
   readonly key: QueryKey;
   /** The query's `meta`, for receivers that haven't called its factory. */
   readonly meta?: QueryMeta;
-  readonly promise?: Promise<unknown>;
+  readonly promise?: Promise<DehydratedResult>;
   /** When `data` was fetched; `0` while pending. */
   readonly updatedAt: number;
 }

package/dist/hydration.mjs

@@ -31,7 +31,10 @@ function dehydrateUnsafe(query, options) {
 		data: serialize(state.data),
 		updatedAt: state.updatedAt
 	};
-	const promise = state.promise.then(serialize, (error) => {
+	const promise = state.promise.then((data) => ({
+		data: serialize(data),
+		updatedAt: getUnsafe(query).updatedAt
+	}), (error) => {
 		throw options.keepErrors ? error : new RedactedError({ hash: query.hash });
 	});
 	promise.catch(noop);
@@ -99,23 +102,36 @@ const dehydrateStream = /*#__PURE__*/ Effect.fnUntraced(function* (queries, subs
 	};
 });
 /**
+* Take the sender's data if it's newer than the entry's. An entry that keeps
+* its own (the sender's is older, as in a router's cached payload) was asked
+* for again, so it revalidates if stale, as `prefetch` would.
+*/
+function takeNewer(entry, data, updatedAt) {
+	const current = entry.state;
+	if (!current.hasData || current.updatedAt < updatedAt) setData(entry, data, updatedAt);
+	else revalidate(entry);
+}
+/**
 * Write dehydrated entries into a cache. Existing entries only take newer
-* 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.
+* data. A pending entry the cache has nothing for resumes the sender's
+* request. One that has data, or a request of its own, waits for the
+* sender's instead of fetching again, and then takes whichever is newer;
+* if the sender's failed, it revalidates.
 */
 function hydrateEntries(entryFor, state, options) {
 	const deserialize = options.deserializeData ?? identity;
 	for (const query of state.queries) {
 		const entry = entryFor(query.key);
 		if (!entry.options && query.meta !== void 0) entry.hydratedMeta = query.meta;
-		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);
+		if (query.updatedAt > 0) takeNewer(entry, deserialize(query.data), query.updatedAt);
+		else if (query.promise) {
+			const result = Promise.resolve(query.promise).then((sent) => ({
+				data: deserialize(sent.data),
+				updatedAt: sent.updatedAt
+			}));
+			if (!entry.state.hasData && !entry.inFlight) resume(entry, result);
+			else result.then((sent) => takeNewer(entry, sent.data, sent.updatedAt), () => revalidate(entry));
+		} else revalidate(entry);
 	}
 }
 //#endregion

package/dist/index.d.mts

@@ -1,9 +1,9 @@
 import { platform_d_exports } from "./platform.mjs";
 import { QueryKey, hashKey, matchesKey } from "./key.mjs";
 import { AnyQueryOptions, DataOf, EnsuredQueryHandle, ErrorOf, InfiniteData, InfiniteQueryOptions, InputArgs, InputOf, IsPaged, LoadOptions, PageFunctionContext, PageOf, QueryBehavior, QueryFactory, QueryFnResult, QueryFunctionContext, QueryHandle, QueryMeta, QueryOptions, Register, RetryPolicy, ServicesOf, infiniteQueryOptions, queryOptions } from "./options.mjs";
-import { DehydrateOptions, DehydratedQuery, DehydratedState, DehydratedStream, HydrateOptions, RedactedError, canDehydrate, dehydrateQuery } from "./hydration.mjs";
+import { DehydrateOptions, DehydratedQuery, DehydratedResult, DehydratedState, DehydratedStream, HydrateOptions, RedactedError, canDehydrate, dehydrateQuery } from "./hydration.mjs";
 import { cache_d_exports } from "./cache.mjs";
 import { Thenable } from "./thenable.mjs";
 import { query_d_exports } from "./query.mjs";
 import { observer_d_exports } from "./observer.mjs";
-export { type AnyQueryOptions, type DataOf, type DehydrateOptions, type DehydratedQuery, type DehydratedState, type DehydratedStream, type EnsuredQueryHandle, type ErrorOf, type HydrateOptions, type InfiniteData, type InfiniteQueryOptions, type InputArgs, type InputOf, type IsPaged, type LoadOptions, type PageFunctionContext, type PageOf, platform_d_exports as Platform, query_d_exports as Query, type QueryBehavior, cache_d_exports as QueryCache, type QueryFactory, type QueryFnResult, type QueryFunctionContext, type QueryHandle, type QueryKey, type QueryMeta, observer_d_exports as QueryObserver, type QueryOptions, RedactedError, type Register, type RetryPolicy, type ServicesOf, type Thenable, canDehydrate, dehydrateQuery, hashKey, infiniteQueryOptions, matchesKey, queryOptions };
+export { type AnyQueryOptions, type DataOf, type DehydrateOptions, type DehydratedQuery, type DehydratedResult, type DehydratedState, type DehydratedStream, type EnsuredQueryHandle, type ErrorOf, type HydrateOptions, type InfiniteData, type InfiniteQueryOptions, type InputArgs, type InputOf, type IsPaged, type LoadOptions, type PageFunctionContext, type PageOf, platform_d_exports as Platform, query_d_exports as Query, type QueryBehavior, cache_d_exports as QueryCache, type QueryFactory, type QueryFnResult, type QueryFunctionContext, type QueryHandle, type QueryKey, type QueryMeta, observer_d_exports as QueryObserver, type QueryOptions, RedactedError, type Register, type RetryPolicy, type ServicesOf, type Thenable, canDehydrate, dehydrateQuery, hashKey, infiniteQueryOptions, matchesKey, queryOptions };

package/package.json

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