@raf-query/core 0.2.8 → 0.3.0

package/CHANGELOG.md

@@ -1,8 +1,18 @@
 # Changelog
 
+## [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
 
@@ -435,7 +434,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 +517,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 +529,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 +569,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.0",
   "description": "Framework-agnostic core of raf-query, a render-as-you-fetch query library",
   "keywords": [
     "query",