@raf-query/react 0.0.2 → 0.0.4

package/CHANGELOG.md

@@ -1,10 +1,20 @@
 # Changelog
 
+## [0.0.4](https://github.com/KATT/raf-query/compare/0.0.3...0.0.4) (2026-10-12)
+
+### Features
+
+* @raf-query/core, @raf-query/react and the example apps ([#1](https://github.com/KATT/raf-query/issues/1)) ([3881014](https://github.com/KATT/raf-query/commit/3881014b7f07d17d733256e184b627ead1f5788b))
+
+## [0.0.3](https://github.com/KATT/raf-query/compare/0.0.2...0.0.3) (2026-10-12)
+
+- lint-fix staged files in pre-commit hook ([#2](https://github.com/KATT/raf-query/issues/2)) ([858a4e0](https://github.com/KATT/raf-query/commit/858a4e02563daec4c6de9a07d438f03573d0339b))
+
 ## [0.0.2](https://github.com/KATT/raf-query/compare/0.0.1...0.0.2) (2026-10-12)
 
 ### Bug Fixes
 
-* resolve workspace packages from source ([f03a57f](https://github.com/KATT/raf-query/commit/f03a57f0d54dbd66d947a0ee97dbb762bddca970))
+- resolve workspace packages from source ([f03a57f](https://github.com/KATT/raf-query/commit/f03a57f0d54dbd66d947a0ee97dbb762bddca970))
 
 ## 0.0.1 (2026-10-12)
 

package/README.md

@@ -8,7 +8,7 @@ The cache's mechanics (dedupe, staleness, retries, infinite paging, SSR hydratio
 
 ## Status
 
-Design spec. This README describes the API being built; nothing is published yet.
+Early. Both packages are on npm at `0.0.x`, and the API can still change between patch releases. [`examples/`](examples/) has the same issue tracker built on TanStack Start and on Next.js App Router.
 
 ## Packages
 
@@ -39,13 +39,13 @@ A query is a **factory**: a function of zero or one argument that returns `query
 ```ts
 import { infiniteQueryOptions, queryOptions } from "@raf-query/react";
 
+// TanStack Start server functions (`createServerFn`); in Next.js, server actions.
+import { getPost, listComments } from "./posts.functions.ts";
+
 export function postQuery(input: { slug: string }) {
 	return queryOptions({
 		queryKey: ["post", input.slug],
-		queryFn: async ({ signal }) => {
-			const res = await fetch(`/api/posts/${input.slug}`, { signal });
-			return (await res.json()) as Post;
-		},
+		queryFn: () => getPost({ data: input }),
 		staleTime: 30_000,
 	});
 }
@@ -53,9 +53,9 @@ export function postQuery(input: { slug: string }) {
 export function commentsQuery(input: { slug: string }) {
 	return infiniteQueryOptions({
 		queryKey: ["comments", input.slug],
-		queryFn: ({ pageParam, signal }) =>
-			api.comments.list({ slug: input.slug, cursor: pageParam }, { signal }),
-		initialPageParam: null as string | null,
+		queryFn: (context) =>
+			listComments({ data: { slug: input.slug, cursor: context.pageParam } }),
+		initialPageParam: 0,
 		getNextPageParam: (lastPage) => lastPage.nextCursor,
 	});
 }
@@ -63,6 +63,8 @@ export function commentsQuery(input: { slug: string }) {
 
 Factories must take at most one argument; the type rejects two or more. The single argument is the query's **input** and must be serializable, because it is what a handle carries.
 
+A `queryFn` returns a value, a promise, or an [Effect](#effect). It receives `queryKey` and an abort `signal`; paged ones also get `pageParam` and `direction`. TypeScript infers the page type from `queryFn`, so if `getNextPageParam` comes first in the object literal (sorted keys), pass the types instead: `infiniteQueryOptions<CommentPage, number>({ ... })`.
+
 The factory is the only place a query is declared paged. Every other API — `prefetch`, `ensure`, `fetch`, `useQuery`, `useWaterfall`, `invalidate`, `setData` — takes either kind and infers the rest from the factory's type.
 
 ## Starting queries
@@ -78,9 +80,10 @@ All three verbs live on the query client and accept a factory plus its input.
 ```tsx
 // TanStack Start
 export const Route = createFileRoute("/posts/$slug")({
-	loader: async ({ context: { queryClient: qc }, params }) => {
-		const comments = qc.prefetch(commentsQuery, { slug: params.slug });
-		const post = await qc.ensure(postQuery, { slug: params.slug });
+	loader: async (args) => {
+		const qc = args.context.queryClient;
+		const comments = qc.prefetch(commentsQuery, { slug: args.params.slug });
+		const post = await qc.ensure(postQuery, { slug: args.params.slug });
 		return { post, comments };
 	},
 	component: PostPage,
@@ -133,26 +136,26 @@ Handles hold no data and no functions. Data reaches the client cache through the
 const [promise, controls] = useQuery(factory, handle, options?);
 ```
 
-`options` takes [`whilePending`](#when-the-url-changes) and per-read refetch settings (`refetchInterval`, `refetchOnWindowFocus`). There is no option to change the input; the handle decides what is read.
+`options` takes [`whilePending`](#when-the-url-changes) and per-read refetch settings (`refetchInterval`, `refetchOnWindowFocus`, `refetchOnReconnect`). There is no option to change the input; the handle decides what is read.
 
 `promise` is a stable `Promise<Data>` owned by the cache. Unwrap it with `use()`. When the cache already has data, the promise is pre-resolved and `use()` returns synchronously without suspending.
 
 ```tsx
 function PostPage() {
 	const loaderData = Route.useLoaderData();
-	const [postPromise, post] = useQuery(postQuery, loaderData.post);
-	const { title, body } = use(postPromise);
+	const [postPromise, postState] = useQuery(postQuery, loaderData.post);
+	const post = use(postPromise);
 
 	return (
 		<article>
-			<h1>{title}</h1>
+			<h1>{post.title}</h1>
 			<button
-				disabled={post.isFetching}
-				onClick={() => startTransition(() => post.refetch())}
+				disabled={postState.isFetching}
+				onClick={() => startTransition(() => postState.refetch())}
 			>
 				Refresh
 			</button>
-			<p>{body}</p>
+			<p>{post.body}</p>
 			<Suspense fallback={<CommentsSkeleton />}>
 				<Comments handle={loaderData.comments} />
 			</Suspense>
@@ -186,11 +189,11 @@ With an `infiniteQueryOptions` factory, `useQuery` returns the same tuple. The p
 ```tsx
 function Comments(props: { handle: QueryHandle<typeof commentsQuery> }) {
 	const [pagesPromise, comments] = useQuery(commentsQuery, props.handle);
-	const { pages } = use(pagesPromise);
+	const data = use(pagesPromise);
 
 	return (
 		<>
-			{pages
+			{data.pages
 				.flatMap((page) => page.items)
 				.map((comment) => (
 					<Comment key={comment.id} {...comment} />
@@ -222,16 +225,16 @@ export const Route = createFileRoute("/posts")({
 		sort: search.sort === "oldest" ? "oldest" : "newest",
 		page: Number(search.page ?? 1),
 	}),
-	loaderDeps: ({ search }) => search,
-	loader: ({ context: { queryClient: qc }, deps }) => ({
-		posts: qc.prefetch(postsQuery, deps),
+	loaderDeps: (args) => args.search,
+	loader: (args) => ({
+		posts: args.context.queryClient.prefetch(postsQuery, args.deps),
 	}),
 	component: PostsPage,
 });
 
 function PostsPage() {
-	const { posts } = Route.useLoaderData();
-	const [postsPromise, postsState] = useQuery(postsQuery, posts, {
+	const loaderData = Route.useLoaderData();
+	const [postsPromise, postsState] = useQuery(postsQuery, loaderData.posts, {
 		whilePending: "previous",
 	});
 
@@ -305,6 +308,13 @@ function PostAuthor(props: { post: Post }) {
 
 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:
+
+```tsx
+const post = await qc.fetch(postQuery, { slug });
+const author = qc.prefetch(authorQuery, { id: post.authorId });
+```
+
 For event-driven preloading, call the client directly: `onPointerEnter={() => qc.prefetch(postQuery, { slug })}`.
 
 ## Mutations
@@ -331,7 +341,7 @@ function EditTitle(props: { post: Post }) {
 }
 ```
 
-`await qc.invalidate(...)` resolves once every query currently being read has refetched, so the action's pending state lasts until the fresh data is on screen.
+`updatePost` is a server function (or a Next.js server action). `await qc.invalidate(...)` resolves once every query currently being read has refetched, so the action's pending state lasts until the fresh data is on screen. For an error message, wrap the action in `useActionState` and return the caught error.
 
 | Call                                  | Effect                                                                  |
 | ------------------------------------- | ----------------------------------------------------------------------- |
@@ -367,7 +377,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.
+`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 generic error, so its message doesn't leak into the page.
 
 ### Next.js App Router
 
@@ -401,11 +411,11 @@ import { HydrationBoundary } from "@raf-query/react/rsc";
 export default async function Page(props: {
 	params: Promise<{ slug: string }>;
 }) {
-	const { slug } = await props.params;
+	const params = await props.params;
 	const qc = getQueryClient();
 
-	const comments = qc.prefetch(commentsQuery, { slug });
-	const post = await qc.fetch(postQuery, { slug });
+	const comments = qc.prefetch(commentsQuery, { slug: params.slug });
+	const post = await qc.fetch(postQuery, { slug: params.slug });
 
 	return (
 		<HydrationBoundary client={qc}>
@@ -422,25 +432,85 @@ 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.
-- `QueryProvider` creates the browser client, and streams queries that client components start during SSR (`useWaterfall`) into the HTML.
+- `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 dedupes them.
+- 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.
 
 #### Server-only queries
 
 A factory that imports server-only code (a database client) can't be imported by a client component, so it can't be read with `useQuery`. Render its data in a server component, or pass a plain promise prop and `use()` it on the client. Refresh it with `router.refresh()`.
 
+## Effect
+
+raf-query runs requests on [Effect](https://effect.website), and Effect code can use it without wrapping:
+
+- A `queryFn` can return an `Effect`. Cancelling the request interrupts it.
+- `retry` accepts a `Schedule` as well as a count or predicate.
+- `qc.effect` has Effect versions of `ensure`, `fetch` and `invalidate`, plus `watch`, a `Stream` of the entry's state.
+
+```ts
+import { Effect, Schedule, Stream } from "effect";
+
+export function issueQuery(input: { id: number }) {
+	return queryOptions({
+		queryKey: ["issue", input.id],
+		queryFn: () => IssueRepo.get(input.id), // Effect<Issue, IssueNotFound>
+		retry: Schedule.exponential("200 millis").pipe(Schedule.upTo({ times: 3 })),
+	});
+}
+
+const program = Effect.gen(function* () {
+	const issue = yield* qc.effect.fetch(issueQuery, { id: 1 });
+	yield* qc.effect.watch(issueQuery, { id: 1 }).pipe(
+		Stream.map((state) => state.data?.title),
+		Stream.runForEach((title) => Effect.log(title)),
+	);
+});
+```
+
+`watch` counts as a reader while it runs, so invalidation and window focus refetch the entry.
+
 ## API reference
 
+`QueryClient`:
+
+| Member                                  | Use                                                                             |
+| --------------------------------------- | ------------------------------------------------------------------------------- |
+| `new QueryClient(config?)`              | `config.defaults` (query options below), `config.onError`, `config.isServer`    |
+| `prefetch`, `ensure`, `fetch`           | [Start queries](#starting-queries)                                              |
+| `invalidate`, `setData`, `getData`      | [Write and read the cache](#mutations)                                          |
+| `effect`                                | [Effect versions](#effect) of `ensure`, `fetch`, `invalidate`, plus `watch`     |
+| `subscribe(listener)`                   | Cache events: `added`, `updated`, `removed`, and `failed` (with the `error`)    |
+| `getAll()`, `getQuery(factory, input?)` | Cache entries, for devtools and integrations                                    |
+| `clear()`                               | Drop every entry and abort in-flight requests                                   |
+| `mount()`                               | Start window-focus and reconnect refetching. The providers call it              |
+| `isServer`                              | Detected from `window`. Server clients don't retry, never gc, skip stale timers |
+
+Query options, accepted by `queryOptions`, `infiniteQueryOptions` and `config.defaults`:
+
+| Option                                                | Default                                   |
+| ----------------------------------------------------- | ----------------------------------------- |
+| `staleTime`                                           | `0` ms                                    |
+| `gcTime`                                              | 5 minutes; `Infinity` on the server       |
+| `retry` (count, `boolean`, predicate, `Schedule`)     | `3`; `0` on the server                    |
+| `retryDelay` (ms, or a function of the failure count) | Doubling from 1 s, at most 30 s           |
+| `refetchOnWindowFocus`, `refetchOnReconnect`          | `true` (only read, stale queries refetch) |
+
+`infiniteQueryOptions` also takes `getPreviousPageParam` and `maxPages`.
+
 `@raf-query/core`:
 
-| Export                                         | Use                                               |
-| ---------------------------------------------- | ------------------------------------------------- |
-| `QueryClient`                                  | The cache. Methods listed above                   |
-| `queryOptions(options)`                        | Typed options for a query factory                 |
-| `infiniteQueryOptions(options)`                | Typed options for a paged query factory           |
-| `allKeyed(record)`                             | Await a record of promises, keeping keys          |
-| `dehydrate(client)` / `hydrate(client, state)` | Low-level cache transfer used by the integrations |
-| `QueryHandle<TFactory>`                        | Handle type for props                             |
+| Export                                         | Use                                                        |
+| ---------------------------------------------- | ---------------------------------------------------------- |
+| `QueryClient`                                  | The cache                                                  |
+| `queryOptions(options)`                        | Typed options for a query factory                          |
+| `infiniteQueryOptions(options)`                | Typed options for a paged query factory                    |
+| `allKeyed(record)`                             | Await a record of promises, keeping keys                   |
+| `dehydrate(client)` / `hydrate(client, state)` | Low-level cache transfer used by the integrations          |
+| `hashKey(key)`, `matchesKey(key, prefix)`      | Key helpers                                                |
+| `CancelledError`                               | Rejection of a request cancelled by `clear()` or a restart |
+| `QueryHandle<TFactory>`                        | Handle type for props                                      |
+| `DataOf<TFactory>`, `InputOf<TFactory>`        | A factory's data and input types                           |
 
 `@raf-query/react` (plus all of the above):
 

package/dist/cast.mjs

@@ -0,0 +1,10 @@
+//#region src/cast.ts
+/**
+* The one place a value's static type is replaced. Every call site states
+* the invariant that makes it sound in a `SAFETY:` comment.
+*/
+function unsafeCast(value) {
+	return value;
+}
+//#endregion
+export { unsafeCast };

package/dist/hydrate.mjs

@@ -0,0 +1,33 @@
+"use client";
+import { useQueryClient } from "./provider.mjs";
+import { hashKey, hydrate } from "@raf-query/core";
+import { useState } from "react";
+//#region src/hydrate.tsx
+const hydratedByClient = /* @__PURE__ */ new WeakMap();
+/** Hashes of entries a client received through {@link Hydrate}. */
+function hydratedHashes(client) {
+	return hydratedByClient.get(client) ?? /* @__PURE__ */ new Set();
+}
+/**
+* Writes dehydrated entries into the provided client before its children
+* render, so their reads find the data (or the server's pending request).
+* Rendered by `HydrationBoundary`; apps don't use it directly.
+*/
+function Hydrate(props) {
+	const client = useQueryClient();
+	const state = props.state;
+	const [hydrated, setHydrated] = useState();
+	if (hydrated !== state) {
+		let hashes = hydratedByClient.get(client);
+		if (!hashes) {
+			hashes = /* @__PURE__ */ new Set();
+			hydratedByClient.set(client, hashes);
+		}
+		for (const query of state.queries) hashes.add(hashKey(query.key));
+		hydrate(client, state, props.options);
+		setHydrated(state);
+	}
+	return props.children;
+}
+//#endregion
+export { Hydrate, hydratedHashes };

package/dist/index.d.mts

@@ -1 +1,5 @@
-export * from "@raf-query/core";
+import { QueryClientProvider, useQueryClient } from "./provider.mjs";
+import { PagingControls, QueryControls, UseQueryControls, UseQueryOptions, UseQueryResult, useQuery } from "./use-query.mjs";
+import { useWaterfall } from "./use-waterfall.mjs";
+export * from "@raf-query/core";
+export { type PagingControls, QueryClientProvider, type QueryControls, type UseQueryControls, type UseQueryOptions, type UseQueryResult, useQuery, useQueryClient, useWaterfall };

package/dist/index.mjs

@@ -1,2 +1,5 @@
+import { QueryClientProvider, useQueryClient } from "./provider.mjs";
+import { useQuery } from "./use-query.mjs";
+import { useWaterfall } from "./use-waterfall.mjs";
 export * from "@raf-query/core";
-export {};
+export { QueryClientProvider, useQuery, useQueryClient, useWaterfall };

package/dist/next.d.mts

@@ -0,0 +1,24 @@
+import { DehydratedState, QueryClientConfig } from "@raf-query/core";
+import { ReactNode } from "react";
+//#region src/next.d.ts
+declare global {
+  /** Entries streamed by `QueryProvider` during SSR, until the browser client takes over. */
+  var RAF_QUERY_SSR: {
+    push(state: DehydratedState): void;
+  } | undefined;
+}
+/**
+ * The query client provider for Next.js App Router. Creates one client per
+ * request during SSR and one per tab in the browser.
+ *
+ * ```tsx
+ * // app/layout.tsx
+ * <QueryProvider>{props.children}</QueryProvider>
+ * ```
+ */
+export declare function QueryProvider(props: {
+  readonly children?: ReactNode;
+  /** Options for the client it creates. */
+  readonly config?: QueryClientConfig;
+}): import("react").JSX.Element;
+//#endregion

package/dist/next.mjs

@@ -0,0 +1,60 @@
+"use client";
+import { QueryClientProvider } from "./provider.mjs";
+import { hydratedHashes } from "./hydrate.mjs";
+import { QueryClient, dehydrateQuery, hydrate } from "@raf-query/core";
+import { useState } from "react";
+import { jsx } from "react/jsx-runtime";
+import { useServerInsertedHTML } from "next/navigation";
+//#region src/next.tsx
+function escapeJson(json) {
+	return json.replaceAll("<", String.raw`\u003c`).replaceAll("\u2028", String.raw`\u2028`).replaceAll("\u2029", String.raw`\u2029`);
+}
+/** Hydrate what SSR streamed so far, then hydrate every later chunk on arrival. */
+function receiveStream(client) {
+	const queued = globalThis.RAF_QUERY_SSR;
+	if (Array.isArray(queued)) for (const state of queued) hydrate(client, state);
+	globalThis.RAF_QUERY_SSR = { push: (state) => hydrate(client, state) };
+}
+/**
+* Streams entries that client components loaded during SSR (`useWaterfall`)
+* into the HTML, ahead of the markup that reads them. Entries that arrived
+* through `HydrationBoundary` are skipped: the RSC payload carries them.
+* Data must be JSON-serializable.
+*/
+function useServerStream(client) {
+	const [sent] = useState(() => /* @__PURE__ */ new Set());
+	useServerInsertedHTML(() => {
+		const hydrated = hydratedHashes(client);
+		const queries = client.getAll().filter((query) => query.getState().hasData && !sent.has(query.hash) && !hydrated.has(query.hash)).map((query) => {
+			sent.add(query.hash);
+			return dehydrateQuery(query);
+		});
+		if (queries.length === 0) return null;
+		const json = escapeJson(JSON.stringify({ queries }));
+		return /* @__PURE__ */ jsx("script", { dangerouslySetInnerHTML: { __html: `(self.RAF_QUERY_SSR=self.RAF_QUERY_SSR||[]).push(${json})` } });
+	});
+}
+/**
+* The query client provider for Next.js App Router. Creates one client per
+* request during SSR and one per tab in the browser.
+*
+* ```tsx
+* // app/layout.tsx
+* <QueryProvider>{props.children}</QueryProvider>
+* ```
+*/
+function QueryProvider(props) {
+	const config = props.config;
+	const [client] = useState(() => {
+		const created = new QueryClient(config);
+		if (!created.isServer) receiveStream(created);
+		return created;
+	});
+	useServerStream(client);
+	return /* @__PURE__ */ jsx(QueryClientProvider, {
+		client,
+		children: props.children
+	});
+}
+//#endregion
+export { QueryProvider };

package/dist/provider.d.mts

@@ -0,0 +1,14 @@
+import { QueryClient } from "@raf-query/core";
+import { ReactNode } from "react";
+//#region src/provider.d.ts
+/**
+ * Provides a client to the tree, and refetches its read, stale queries on
+ * window focus and reconnect while mounted.
+ */
+export declare function QueryClientProvider(props: {
+  readonly children?: ReactNode;
+  readonly client: QueryClient;
+}): import("react").JSX.Element;
+/** The client from the nearest {@link QueryClientProvider}. */
+export declare function useQueryClient(): QueryClient;
+//#endregion

package/dist/provider.mjs

@@ -0,0 +1,25 @@
+"use client";
+import { createContext, use, useEffect } from "react";
+import { jsx } from "react/jsx-runtime";
+//#region src/provider.tsx
+const QueryClientContext = createContext(null);
+/**
+* Provides a client to the tree, and refetches its read, stale queries on
+* window focus and reconnect while mounted.
+*/
+function QueryClientProvider(props) {
+	const client = props.client;
+	useEffect(() => client.mount(), [client]);
+	return /* @__PURE__ */ jsx(QueryClientContext, {
+		value: client,
+		children: props.children
+	});
+}
+/** The client from the nearest {@link QueryClientProvider}. */
+function useQueryClient() {
+	const client = use(QueryClientContext);
+	if (!client) throw new Error("useQueryClient: no QueryClientProvider above this component");
+	return client;
+}
+//#endregion
+export { QueryClientProvider, useQueryClient };

package/dist/rsc.d.mts

@@ -0,0 +1,25 @@
+import { DehydrateOptions, QueryClient } from "@raf-query/core";
+import { ReactNode } from "react";
+//#region src/rsc.d.ts
+/**
+ * Server component: sends the request client's entries to the browser cache.
+ * Pending entries cross as promises and stream in as they settle. Entries an
+ * earlier boundary already sent in this request are skipped.
+ *
+ * ```tsx
+ * const qc = getQueryClient();
+ * const comments = qc.prefetch(commentsQuery, { slug });
+ * return (
+ *   <HydrationBoundary client={qc}>
+ *     <Comments handle={comments} />
+ *   </HydrationBoundary>
+ * );
+ * ```
+ */
+export declare function HydrationBoundary(props: {
+  readonly children?: ReactNode;
+  /** The request's server client (e.g. from React's `cache()`). */
+  readonly client: QueryClient;
+  readonly options?: DehydrateOptions;
+}): import("react").JSX.Element;
+//#endregion

package/dist/rsc.mjs

@@ -0,0 +1,41 @@
+import { Hydrate } from "./hydrate.mjs";
+import { canDehydrate, dehydrate, hashKey } from "@raf-query/core";
+import { jsx } from "react/jsx-runtime";
+//#region src/rsc.tsx
+const sentByClient = /* @__PURE__ */ new WeakMap();
+/**
+* Server component: sends the request client's entries to the browser cache.
+* Pending entries cross as promises and stream in as they settle. Entries an
+* earlier boundary already sent in this request are skipped.
+*
+* ```tsx
+* const qc = getQueryClient();
+* const comments = qc.prefetch(commentsQuery, { slug });
+* return (
+*   <HydrationBoundary client={qc}>
+*     <Comments handle={comments} />
+*   </HydrationBoundary>
+* );
+* ```
+*/
+function HydrationBoundary(props) {
+	const client = props.client;
+	let sent = sentByClient.get(client);
+	if (!sent) {
+		sent = /* @__PURE__ */ new Set();
+		sentByClient.set(client, sent);
+	}
+	const alreadySent = sent;
+	const filter = props.options?.filter ?? canDehydrate;
+	const state = dehydrate(client, {
+		...props.options,
+		filter: (query) => !alreadySent.has(query.hash) && filter(query)
+	});
+	for (const query of state.queries) alreadySent.add(hashKey(query.key));
+	return /* @__PURE__ */ jsx(Hydrate, {
+		state,
+		children: props.children
+	});
+}
+//#endregion
+export { HydrationBoundary };

package/dist/tanstack-router.d.mts

@@ -0,0 +1,24 @@
+import { DehydrateOptions, HydrateOptions, QueryClient } from "@raf-query/core";
+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:
+ *
+ * - During SSR, sends the cache to the browser with the router's dehydrated
+ *   state, then streams entries as they start or settle. Pending entries
+ *   cross as promises, so the browser resumes them instead of refetching.
+ * - Clears the request's cache when the response finishes.
+ * - Turns `redirect()` thrown from a `queryFn` into a navigation.
+ *
+ * Call it in `getRouter`, which runs once per request on the server.
+ */
+export declare function setupRouterIntegration<TRouter extends AnyRouter>(options: RouterIntegrationOptions<TRouter>): void;
+//#endregion

package/dist/tanstack-router.mjs

@@ -0,0 +1,130 @@
+import { canDehydrate, dehydrateQuery, hydrate } from "@raf-query/core";
+import { isRedirect } from "@tanstack/react-router";
+import { Predicate } from "effect";
+//#region src/tanstack-router.ts
+const noop = () => {};
+function setupServer(options) {
+	const router = options.router;
+	const queryClient = options.queryClient;
+	const dehydrateOptions = options.dehydrateOptions;
+	const shouldSend = dehydrateOptions?.filter ?? canDehydrate;
+	const originalDehydrate = router.options.dehydrate;
+	let finish = noop;
+	let cleanedUp = false;
+	const teardown = () => {
+		cleanedUp = true;
+		finish();
+		queryClient.clear();
+	};
+	router.serverSsrLifecycle = {
+		...router.serverSsrLifecycle,
+		onServerSsrAttach: [...router.serverSsrLifecycle?.onServerSsrAttach ?? [], (serverSsr) => serverSsr.onCleanup(teardown)]
+	};
+	router.options.dehydrate = async () => {
+		const dehydrated = await originalDehydrate?.();
+		if (cleanedUp) {
+			queryClient.clear();
+			return;
+		}
+		const sent = /* @__PURE__ */ new Set();
+		const initial = [];
+		for (const query of queryClient.getAll()) if (shouldSend(query)) {
+			initial.push(dehydrateQuery(query, dehydrateOptions));
+			sent.add(query.hash);
+		}
+		let controller;
+		const stream = new ReadableStream({ start(streamController) {
+			controller = streamController;
+		} });
+		let batch;
+		const flush = () => {
+			const queries = batch;
+			batch = void 0;
+			if (!queries || !controller) return;
+			const chunk = [];
+			for (const query of queries.values()) if (!sent.has(query.hash) && shouldSend(query)) {
+				chunk.push(dehydrateQuery(query, dehydrateOptions));
+				sent.add(query.hash);
+			}
+			if (chunk.length > 0) controller.enqueue(chunk);
+		};
+		const unsubscribe = queryClient.subscribe((event) => {
+			if (event.type === "removed" || sent.has(event.query.hash)) return;
+			if (!batch) {
+				batch = /* @__PURE__ */ new Map();
+				queueMicrotask(flush);
+			}
+			batch.set(event.query.hash, event.query);
+		});
+		finish = () => {
+			finish = noop;
+			flush();
+			unsubscribe();
+			try {
+				controller?.close();
+			} catch {}
+		};
+		router.serverSsr?.onRenderFinished(() => finish());
+		return {
+			...dehydrated,
+			raf: {
+				initial,
+				stream
+			}
+		};
+	};
+}
+function hasRafQueries(value) {
+	return Predicate.hasProperty(value, "raf") && Predicate.isObject(value.raf);
+}
+function setupClient(options) {
+	const router = options.router;
+	const queryClient = options.queryClient;
+	const hydrateOptions = options.hydrateOptions;
+	const originalHydrate = router.options.hydrate;
+	router.options.hydrate = async (dehydrated) => {
+		await originalHydrate?.(dehydrated);
+		if (!hasRafQueries(dehydrated)) return;
+		hydrate(queryClient, { queries: dehydrated.raf.initial }, hydrateOptions);
+		const reader = dehydrated.raf.stream.getReader();
+		(async () => {
+			try {
+				for (;;) {
+					const chunk = await reader.read();
+					if (chunk.done) return;
+					hydrate(queryClient, { queries: chunk.value }, hydrateOptions);
+				}
+			} catch (error) {
+				console.error("raf-query: reading the query stream failed", error);
+				reader.cancel(error).catch(() => {});
+			} finally {
+				reader.releaseLock();
+			}
+		})();
+	};
+}
+/**
+* Connects a query client to a TanStack Router (and TanStack Start) router:
+*
+* - During SSR, sends the cache to the browser with the router's dehydrated
+*   state, then streams entries as they start or settle. Pending entries
+*   cross as promises, so the browser resumes them instead of refetching.
+* - Clears the request's cache when the response finishes.
+* - Turns `redirect()` thrown from a `queryFn` into a navigation.
+*
+* Call it in `getRouter`, which runs once per request on the server.
+*/
+function setupRouterIntegration(options) {
+	const router = options.router;
+	if (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);
+		}
+	});
+}
+//#endregion
+export { setupRouterIntegration };

package/dist/use-query.d.mts

@@ -0,0 +1,64 @@
+import { DataOf, InputOf, IsPaged, QueryClient, QueryFactory, QueryHandle, QueryKey } from "@raf-query/core";
+//#region src/use-query.d.ts
+export interface UseQueryOptions {
+  /** Refetch on this interval (ms) while mounted and the page is visible. */
+  readonly refetchInterval?: number;
+  /** Refetch on reconnect while stale. Default: the query's option, else `true`. */
+  readonly refetchOnReconnect?: boolean;
+  /** Refetch on window focus while stale. Default: the query's option, else `true`. */
+  readonly refetchOnWindowFocus?: boolean;
+  /**
+   * What to render while the handle's input has no data yet:
+   * - `"suspend"` (default): the promise is pending, so `use()` suspends.
+   * - `"previous"`: keep returning the last input's data, with `isPrevious`.
+   */
+  readonly whilePending?: "previous" | "suspend";
+}
+/** The second element of {@link useQuery}'s result. */
+export interface QueryControls<TFactory extends QueryFactory> {
+  /** Error of the last failed request. Existing data stays readable. */
+  readonly error: unknown;
+  /** Stable string form of the handle's key, for `key` props. */
+  readonly hash: string;
+  /** Input of the data in the promise; differs from the handle's while `isPrevious`. */
+  readonly input: InputOf<TFactory>;
+  /** A request is in flight: first load, new input, or background refetch. */
+  readonly isFetching: boolean;
+  /** No data yet for the handle's input. */
+  readonly isPending: boolean;
+  /** The promise holds a previous input's data (`whilePending: "previous"`). */
+  readonly isPrevious: boolean;
+  /** The data is older than `staleTime`, or was invalidated. */
+  readonly isStale: boolean;
+  /** Key of the data in the promise; differs from the handle's while `isPrevious`. */
+  readonly key: QueryKey;
+  /** Refetch now. Resolves when the request settles; never rejects. */
+  refetch(): Promise<void>;
+  /** When the data in the promise was fetched (ms since epoch); `0` before that. */
+  readonly updatedAt: number;
+}
+/** Extra controls for factories that return `infiniteQueryOptions(...)`. */
+export interface PagingControls {
+  fetchNextPage(): Promise<void>;
+  fetchPreviousPage(): Promise<void>;
+  readonly hasNextPage: boolean;
+  readonly hasPreviousPage: boolean;
+  readonly isFetchingNextPage: boolean;
+  readonly isFetchingPreviousPage: boolean;
+}
+export type UseQueryControls<TFactory extends QueryFactory> = IsPaged<TFactory> extends true ? QueryControls<TFactory> & PagingControls : QueryControls<TFactory>;
+export type UseQueryResult<TFactory extends QueryFactory> = readonly [promise: Promise<DataOf<TFactory>>, controls: UseQueryControls<TFactory>];
+/**
+ * Read the query a handle points at. Returns a promise to unwrap with
+ * `use()` and the query's controls:
+ *
+ * ```tsx
+ * const [postPromise, postState] = useQuery(postQuery, loaderData.post);
+ * const post = use(postPromise);
+ * ```
+ *
+ * The promise is stable per data version and already fulfilled once the
+ * cache has data, so `use()` only suspends while there is nothing to show.
+ */
+export declare function useQuery<TFactory extends QueryFactory>(factory: TFactory, handle: QueryHandle<TFactory>, options?: UseQueryOptions): UseQueryResult<TFactory>;
+//#endregion

package/dist/use-query.mjs

@@ -0,0 +1,82 @@
+"use client";
+import { useQueryClient } from "./provider.mjs";
+import { unsafeCast } from "./cast.mjs";
+import { useCallback, useEffect, useState, useSyncExternalStore } from "react";
+//#region src/use-query.ts
+function queryFor(client, factory, input) {
+	const args = [input];
+	return client.getQuery(factory, ...args);
+}
+function useRefetchInterval(query, interval) {
+	useEffect(() => {
+		if (interval === void 0 || !Number.isFinite(interval) || interval <= 0) return;
+		const timer = setInterval(() => {
+			if (document.visibilityState !== "hidden") query.refetch();
+		}, interval);
+		return () => clearInterval(timer);
+	}, [query, interval]);
+}
+/**
+* Read the query a handle points at. Returns a promise to unwrap with
+* `use()` and the query's controls:
+*
+* ```tsx
+* const [postPromise, postState] = useQuery(postQuery, loaderData.post);
+* const post = use(postPromise);
+* ```
+*
+* The promise is stable per data version and already fulfilled once the
+* cache has data, so `use()` only suspends while there is nothing to show.
+*/
+function useQuery(factory, handle, options = {}) {
+	const query = queryFor(useQueryClient(), factory, handle.input);
+	query.read();
+	const refetchOnReconnect = options.refetchOnReconnect;
+	const refetchOnWindowFocus = options.refetchOnWindowFocus;
+	const subscribe = useCallback((onChange) => query.subscribe(onChange, {
+		refetchOnReconnect,
+		refetchOnWindowFocus
+	}), [
+		query,
+		refetchOnReconnect,
+		refetchOnWindowFocus
+	]);
+	const state = useSyncExternalStore(subscribe, query.getState, query.getState);
+	useRefetchInterval(query, options.refetchInterval);
+	const keepPrevious = options.whilePending === "previous";
+	const [lastShown, setLastShown] = useState(void 0);
+	if (keepPrevious && state.hasData && lastShown?.promise !== state.promise) setLastShown({
+		handle: query.handle,
+		hash: query.hash,
+		promise: state.promise,
+		updatedAt: state.updatedAt
+	});
+	const previous = keepPrevious && !state.hasData && state.status !== "error" && lastShown !== void 0 && lastShown.hash !== query.hash ? lastShown : void 0;
+	const shown = previous ?? {
+		handle: query.handle,
+		hash: query.hash,
+		promise: state.promise,
+		updatedAt: state.updatedAt
+	};
+	const controls = {
+		error: state.error,
+		fetchNextPage: query.fetchNextPage,
+		fetchPreviousPage: query.fetchPreviousPage,
+		hash: query.hash,
+		hasNextPage: query.hasNextPage(),
+		hasPreviousPage: query.hasPreviousPage(),
+		input: shown.handle.input,
+		isFetching: state.isFetching,
+		isFetchingNextPage: state.fetchDirection === "forward",
+		isFetchingPreviousPage: state.fetchDirection === "backward",
+		isPending: !state.hasData,
+		isPrevious: previous !== void 0,
+		isStale: state.isStale,
+		key: shown.handle.key,
+		refetch: query.refetch,
+		updatedAt: shown.updatedAt
+	};
+	return unsafeCast([shown.promise, controls]);
+}
+//#endregion
+export { queryFor, useQuery };

package/dist/use-waterfall.d.mts

@@ -0,0 +1,14 @@
+import { InputArgs, QueryFactory, QueryHandle } from "@raf-query/core";
+//#region src/use-waterfall.d.ts
+/**
+ * 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.
+ *
+ * ```tsx
+ * const author = useWaterfall(authorQuery, { id: post.authorId });
+ * const [authorPromise] = useQuery(authorQuery, author);
+ * ```
+ */
+export declare function useWaterfall<TFactory extends QueryFactory>(factory: TFactory, ...args: InputArgs<TFactory>): QueryHandle<TFactory>;
+//#endregion

package/dist/use-waterfall.mjs

@@ -0,0 +1,20 @@
+"use client";
+import { useQueryClient } from "./provider.mjs";
+//#region src/use-waterfall.ts
+/**
+* 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.
+*
+* ```tsx
+* const author = useWaterfall(authorQuery, { id: post.authorId });
+* const [authorPromise] = useQuery(authorQuery, author);
+* ```
+*/
+function useWaterfall(factory, ...args) {
+	const query = useQueryClient().getQuery(factory, ...args);
+	query.read();
+	return query.handle;
+}
+//#endregion
+export { useWaterfall };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@raf-query/react",
-  "version": "0.0.2",
+  "version": "0.0.4",
   "description": "React bindings for raf-query, a render-as-you-fetch query library",
   "keywords": [
     "query",
@@ -32,21 +32,40 @@
   "type": "module",
   "sideEffects": false,
   "exports": {
-    ".": "./dist/index.mjs"
+    ".": "./dist/index.mjs",
+    "./next": "./dist/next.mjs",
+    "./rsc": "./dist/rsc.mjs",
+    "./tanstack-router": "./dist/tanstack-router.mjs"
   },
   "dependencies": {
-    "@raf-query/core": "0.0.2",
+    "@raf-query/core": "0.0.4",
     "effect": "^4.0.1"
   },
   "peerDependencies": {
+    "@tanstack/react-router": "^1.170.0",
+    "next": "^16.0.0",
     "react": "^19.2.0"
   },
+  "peerDependenciesMeta": {
+    "@tanstack/react-router": {
+      "optional": true
+    },
+    "next": {
+      "optional": true
+    }
+  },
   "devDependencies": {
     "@effect/vitest": "4.0.1",
+    "@tanstack/react-router": "1.170.42",
+    "@testing-library/react": "16.3.3",
     "@types/node": "26.6.4",
     "@types/react": "19.3.0",
+    "@types/react-dom": "19.3.0",
     "@vitest/coverage-v8": "5.0.1",
+    "happy-dom": "21.0.1",
+    "next": "16.4.0",
     "react": "19.3.0",
+    "react-dom": "19.3.0",
     "typescript": "7.0.2",
     "vite-plus": "1.0.0"
   },