@raf-query/react 0.8.0 → 0.9.0

package/CHANGELOG.md

@@ -1,18 +1,33 @@
 # Changelog
 
+## [0.9.0](https://github.com/KATT/raf-query/compare/0.8.0...0.9.0) (2026-10-15)
+
+### ⚠ BREAKING CHANGES
+
+* useQuery returns the data for a handle from ensure or fetch ([#144](https://github.com/KATT/raf-query/issues/144))
+
+### Features
+
+* useQuery returns the data for a handle from ensure or fetch ([#144](https://github.com/KATT/raf-query/issues/144)) ([1845244](https://github.com/KATT/raf-query/commit/18452443ba61c205a53c4f71d60ec99a9b8620a7)), references [#142](https://github.com/KATT/raf-query/issues/142)
+
+### Documentation
+
+* call the early API a note about minor releases ([#143](https://github.com/KATT/raf-query/issues/143)) ([2d79eed](https://github.com/KATT/raf-query/commit/2d79eed7b107b6d16898ebb203a9bdfcfb3856c4))
+* show prefetch and ensure, and make list queries infinite ([#140](https://github.com/KATT/raf-query/issues/140)) ([25cfaa0](https://github.com/KATT/raf-query/commit/25cfaa08f9f192af7efded1269f4ae8a9e5f1026))
+
 ## [0.8.0](https://github.com/KATT/raf-query/compare/0.7.12...0.8.0) (2026-10-15)
 
 ### ⚠ BREAKING CHANGES
 
-* ensure and fetch return a QueryHandleWithData ([#142](https://github.com/KATT/raf-query/issues/142))
+- ensure and fetch return a QueryHandleWithData ([#142](https://github.com/KATT/raf-query/issues/142))
 
 ### Features
 
-* ensure and fetch return a QueryHandleWithData ([#142](https://github.com/KATT/raf-query/issues/142)) ([504cd2a](https://github.com/KATT/raf-query/commit/504cd2a19e04b614eb648f02b256128c4eb31d38))
+- ensure and fetch return a QueryHandleWithData ([#142](https://github.com/KATT/raf-query/issues/142)) ([504cd2a](https://github.com/KATT/raf-query/commit/504cd2a19e04b614eb648f02b256128c4eb31d38))
 
 ### Miscellaneous Chores
 
-* group experiments under `.experimental/<topic>/` ([#137](https://github.com/KATT/raf-query/issues/137)) ([52ce752](https://github.com/KATT/raf-query/commit/52ce7522223346e82687338d6ac6d34f793b6fcf))
+- group experiments under `.experimental/<topic>/` ([#137](https://github.com/KATT/raf-query/issues/137)) ([52ce752](https://github.com/KATT/raf-query/commit/52ce7522223346e82687338d6ac6d34f793b6fcf))
 
 ## [0.7.12](https://github.com/KATT/raf-query/compare/0.7.11...0.7.12) (2026-10-15)
 

package/README.md

@@ -4,22 +4,23 @@ Render-as-you-fetch data fetching for React: start queries in route loaders and
 
 **[Documentation](https://raf-query.katt.dev)** · [Quick start](https://raf-query.katt.dev/docs/quick-start) · [API reference](https://raf-query.katt.dev/docs/api-reference) · [GitHub](https://github.com/KATT/raf-query)
 
-> [!WARNING]
-> raf-query is early. The API can still change between patch releases, and you use it at your own risk.
+> [!NOTE]
+> raf-query is early. The API can still change between minor releases, and you use it at your own risk.
 
 ## Install
 
 ```bash
-npm install @raf-query/react
+npm install @raf-query/react effect
 ```
 
-`effect` is a peer dependency. npm, pnpm and Bun install it for you; with Yarn, run `yarn add @raf-query/react effect`. Apps never import it unless they write Effect code. Requires React 19.2 or newer.
+Apps never import `effect` unless they write Effect code. Requires React 19.2 or newer.
 
 ## Usage
 
+A query is a factory. The loader and the component call the same one. A paged list, such as comments, uses `infiniteQueryOptions`.
+
 ```tsx
-import { queryOptions, useQuery } from "@raf-query/react";
-import { use } from "react";
+import { infiniteQueryOptions, queryOptions } from "@raf-query/react";
 
 export function postQuery(input: { slug: string }) {
 	return queryOptions({
@@ -28,20 +29,96 @@ export function postQuery(input: { slug: string }) {
 	});
 }
 
-// The loader starts the query and passes a handle on…
+export function commentsQuery(input: { slug: string }) {
+	return infiniteQueryOptions({
+		queryKey: ["comments", input.slug],
+		queryFn: (context) =>
+			listComments({ cursor: context.pageParam, slug: input.slug }),
+		initialPageParam: 0,
+		getNextPageParam: (lastPage) => lastPage.nextCursor,
+	});
+}
+```
+
+**`prefetch`** starts the request and returns a handle at once. The page renders now; `use()` suspends whatever is still loading, under its Suspense fallback.
+
+```tsx
+import { type QueryHandle, useQuery } from "@raf-query/react";
+import { Suspense, use } from "react";
+
+export const Route = createFileRoute("/posts/$slug")({
+	loader: (args) => {
+		const qc = args.context.queryClient;
+		const { slug } = args.params;
+		return {
+			comments: qc.prefetch(commentsQuery, { slug }),
+			post: qc.prefetch(postQuery, { slug }),
+		};
+	},
+	component: PostPage,
+});
+
+function PostPage() {
+	const data = Route.useLoaderData();
+	const [postPromise] = useQuery(postQuery, data.post);
+	const post = use(postPromise);
+	return (
+		<article>
+			<h1>{post.title}</h1>
+			<Suspense fallback={<CommentsSkeleton />}>
+				<Comments handle={data.comments} />
+			</Suspense>
+		</article>
+	);
+}
+
+function Comments(props: { handle: QueryHandle<typeof commentsQuery> }) {
+	const [pagesPromise] = useQuery(commentsQuery, props.handle);
+	const pages = use(pagesPromise);
+	return pages.pages
+		.flatMap((page) => page.items)
+		.map((comment) => (
+			<p key={comment.id}>
+				<strong>{comment.author}</strong> {comment.body}
+			</p>
+		));
+}
+```
+
+**`ensure`** waits until the data is cached, so the navigation holds. `useQuery` returns the data itself for that handle, not a promise. Await the post and its comments together with [`allKeyed`](https://raf-query.katt.dev/docs/starting-queries#awaiting-several-queries) — a record of promises in, the same record out — so one wait never delays the other.
+
+```tsx
+import { allKeyed, useQuery } from "@raf-query/react";
+
 export const Route = createFileRoute("/posts/$slug")({
-	loader: async (args) => ({
-		post: await args.context.queryClient.ensure(postQuery, {
-			slug: args.params.slug,
-		}),
-	}),
+	loader: (args) => {
+		const qc = args.context.queryClient;
+		const { slug } = args.params;
+		return allKeyed({
+			comments: qc.ensure(commentsQuery, { slug }),
+			post: qc.ensure(postQuery, { slug }),
+		});
+	},
 	component: PostPage,
 });
 
-// …and the component reads it.
 function PostPage() {
-	const [post] = useQuery(postQuery, Route.useLoaderData().post);
-	return <h1>{use(post).title}</h1>;
+	const data = Route.useLoaderData();
+	// Both already waited, so these are the data itself.
+	const [post] = useQuery(postQuery, data.post);
+	const [pages] = useQuery(commentsQuery, data.comments);
+	return (
+		<article>
+			<h1>{post.title}</h1>
+			{pages.pages
+				.flatMap((page) => page.items)
+				.map((comment) => (
+					<p key={comment.id}>
+						<strong>{comment.author}</strong> {comment.body}
+					</p>
+				))}
+		</article>
+	);
 }
 ```
 

package/dist/index.d.mts

@@ -2,7 +2,7 @@ import { QueryClient, QueryClientConfig, dehydrate, hydrate } from "./client.mjs
 import { Settled, allKeyed } from "./all-keyed.mjs";
 import { QueryClientProvider, useQueryClient } from "./provider.mjs";
 import { useIsFetching } from "./use-is-fetching.mjs";
-import { HasTypedError, PagingControls, QueryControls, ThrowsOnError, UseQueryControls, UseQueryOptions, UseQueryResult, UseQueryThrowOptions, useQuery } from "./use-query.mjs";
+import { HasTypedError, PagingControls, QueryControls, ThrowsOnError, UseQueryControls, UseQueryOptions, UseQueryResult, UseQueryResultWithData, UseQueryThrowOptions, useQuery } from "./use-query.mjs";
 import { useWaterfall } from "./use-waterfall.mjs";
 export * from "@raf-query/core";
-export { type HasTypedError, type PagingControls, QueryClient, type QueryClientConfig, QueryClientProvider, type QueryControls, type Settled, type ThrowsOnError, type UseQueryControls, type UseQueryOptions, type UseQueryResult, type UseQueryThrowOptions, allKeyed, dehydrate, hydrate, useIsFetching, useQuery, useQueryClient, useWaterfall };
+export { type HasTypedError, type PagingControls, QueryClient, type QueryClientConfig, QueryClientProvider, type QueryControls, type Settled, type ThrowsOnError, type UseQueryControls, type UseQueryOptions, type UseQueryResult, type UseQueryResultWithData, type UseQueryThrowOptions, allKeyed, dehydrate, hydrate, useIsFetching, useQuery, useQueryClient, useWaterfall };

package/dist/use-query.d.mts

@@ -1,4 +1,4 @@
-import { DataOf, ErrorOf, InputOf, IsPaged, QueryFactory, QueryHandle, QueryKey, QueryObserver } from "@raf-query/core";
+import { DataOf, ErrorOf, InputOf, IsPaged, QueryFactory, QueryHandle, QueryHandleWithData, QueryKey, QueryObserver } from "@raf-query/core";
 import { Result } from "effect";
 //#region src/use-query.d.ts
 /** `refetchInterval`, `refetchOnWindowFocus`, `refetchOnReconnect`, `whilePending`. */
@@ -63,6 +63,8 @@ export type HasTypedError<TFactory extends QueryFactory> = unknown extends Error
  */
 export type ThrowsOnError<TFactory extends QueryFactory, TThrow extends boolean | undefined> = HasTypedError<TFactory> extends false ? true : TThrow extends boolean ? TThrow : false;
 export type UseQueryResult<TFactory extends QueryFactory, TThrow extends boolean | undefined = undefined> = ThrowsOnError<TFactory, TThrow> extends true ? readonly [promise: Promise<DataOf<TFactory>>, controls: UseQueryControls<TFactory>] : readonly [promise: Promise<Result.Result<DataOf<TFactory>, ErrorOf<TFactory>>>, controls: UseQueryControls<TFactory>];
+/** {@link useQuery}'s result for a handle from `ensure` or `fetch`. */
+export type UseQueryResultWithData<TFactory extends QueryFactory, TThrow extends boolean | undefined = undefined> = ThrowsOnError<TFactory, TThrow> extends true ? readonly [data: DataOf<TFactory>, controls: UseQueryControls<TFactory>] : readonly [result: Result.Result<DataOf<TFactory>, ErrorOf<TFactory>>, controls: UseQueryControls<TFactory>];
 /**
  * Read the query a handle points at. Returns a promise to unwrap with
  * `use()` and the query's controls:
@@ -87,11 +89,25 @@ export type UseQueryResult<TFactory extends QueryFactory, TThrow extends boolean
  * The component re-renders when the promise changes, and when a control it
  * has read changes; changes to controls it never reads are skipped.
  *
- * A handle from `ensure` or `fetch` reads the same way: the hook reads the
- * live entry, not the handle's `data` snapshot, and its promise is already
- * fulfilled unless the entry has lost its data since (garbage-collected,
- * `reset`).
+ * A handle from `ensure` or `fetch` already has its data, so the hook
+ * unwraps the promise itself and returns the data (or `Result`):
+ *
+ * ```tsx
+ * const [post, postState] = useQuery(postQuery, loaderData.post);
+ * ```
+ *
+ * It reads the live entry, not the handle's `data` snapshot. If that entry
+ * has lost its data since (garbage-collected, `reset`), the hook suspends
+ * until it is refetched.
+ *
+ * The hook picks by the handle at runtime (`data` in it), so a prop that
+ * receives a handle from `ensure` / `fetch` must be typed
+ * {@link QueryHandleWithData}: typed as `QueryHandle`, it reads as a promise
+ * while the hook returns the data.
  */
+export declare function useQuery<TFactory extends QueryFactory, const TThrow extends boolean | undefined = undefined>(factory: TFactory, handle: QueryHandleWithData<TFactory>, options?: UseQueryOptions & UseQueryThrowOptions<TFactory> & {
+  readonly throwOnError?: TThrow;
+}): UseQueryResultWithData<TFactory, TThrow>;
 export declare function useQuery<TFactory extends QueryFactory, const TThrow extends boolean | undefined = undefined>(factory: TFactory, handle: QueryHandle<TFactory>, options?: UseQueryOptions & UseQueryThrowOptions<TFactory> & {
   readonly throwOnError?: TThrow;
 }): UseQueryResult<TFactory, TThrow>;

package/dist/use-query.mjs

@@ -3,7 +3,7 @@ import { useQueryClient } from "./provider.mjs";
 import { assertSent } from "./browser-requests.mjs";
 import { Query, QueryObserver, fulfilled, pending } from "@raf-query/core";
 import { Effect, Result } from "effect";
-import { useEffect, useState, useSyncExternalStore } from "react";
+import { use, useEffect, useState, useSyncExternalStore } from "react";
 //#region src/use-query.ts
 function queryFor(client, factory, input) {
 	const args = [input];
@@ -87,7 +87,14 @@ function useQuery(factory, handle, options = {}) {
 	]);
 	QueryObserver.trackProp(observer, "promise");
 	const controls = withPromiseCommands(QueryObserver.trackResult(observer, result));
-	if (!(options.throwOnError ?? client.throwOnError)) return [asResultThenable(result.promise), controls];
+	const throwOnError = options.throwOnError ?? client.throwOnError;
+	const withData = "data" in handle;
+	if (!throwOnError) {
+		const resultPromise = asResultThenable(result.promise);
+		if (withData) return [use(resultPromise), controls];
+		return [resultPromise, controls];
+	}
+	if (withData) return [use(result.promise), controls];
 	return [result.promise, controls];
 }
 //#endregion

package/package.json

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