@raf-query/react 0.7.12 → 0.9.0

package/CHANGELOG.md

@@ -1,15 +1,44 @@
 # 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))
+
+### 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))
+
+### 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))
+
 ## [0.7.12](https://github.com/KATT/raf-query/compare/0.7.11...0.7.12) (2026-10-15)
 
-* add knip with every issue type as an error ([#129](https://github.com/KATT/raf-query/issues/129)) ([603719d](https://github.com/KATT/raf-query/commit/603719dcb834312d4a813ecae865df7d56faf8c5))
-* cache Next.js Turbopack builds ([#128](https://github.com/KATT/raf-query/issues/128)) ([667b38f](https://github.com/KATT/raf-query/commit/667b38ff5728dad3fdad6d90445aea480cfbd063))
-* explain how a route loads its data on the homepage ([#121](https://github.com/KATT/raf-query/issues/121)) ([ec1d6ef](https://github.com/KATT/raf-query/commit/ec1d6efdad75ea2d05dd56790e5e980756afea13))
-* frame the cache as async data, not server-state-only ([#126](https://github.com/KATT/raf-query/issues/126)) ([db9ba02](https://github.com/KATT/raf-query/commit/db9ba02995aa01cadacb2739fd258de3c920d440))
+- add knip with every issue type as an error ([#129](https://github.com/KATT/raf-query/issues/129)) ([603719d](https://github.com/KATT/raf-query/commit/603719dcb834312d4a813ecae865df7d56faf8c5))
+- cache Next.js Turbopack builds ([#128](https://github.com/KATT/raf-query/issues/128)) ([667b38f](https://github.com/KATT/raf-query/commit/667b38ff5728dad3fdad6d90445aea480cfbd063))
+- explain how a route loads its data on the homepage ([#121](https://github.com/KATT/raf-query/issues/121)) ([ec1d6ef](https://github.com/KATT/raf-query/commit/ec1d6efdad75ea2d05dd56790e5e980756afea13))
+- frame the cache as async data, not server-state-only ([#126](https://github.com/KATT/raf-query/issues/126)) ([db9ba02](https://github.com/KATT/raf-query/commit/db9ba02995aa01cadacb2739fd258de3c920d440))
 
 ### Features
 
-* **examples:** reinstall shadcn on Base UI without Radix ([#125](https://github.com/KATT/raf-query/issues/125)) ([7c13ef3](https://github.com/KATT/raf-query/commit/7c13ef379dc297edbbe160516b26916d465a48d1))
+- **examples:** reinstall shadcn on Base UI without Radix ([#125](https://github.com/KATT/raf-query/issues/125)) ([7c13ef3](https://github.com/KATT/raf-query/commit/7c13ef379dc297edbbe160516b26916d465a48d1))
 
 ## [0.7.11](https://github.com/KATT/raf-query/compare/0.7.10...0.7.11) (2026-10-14)
 

package/README.md

@@ -4,21 +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 { infiniteQueryOptions, queryOptions } from "@raf-query/react";
 
 export function postQuery(input: { slug: string }) {
 	return queryOptions({
@@ -27,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>{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/client.d.mts

@@ -1,4 +1,4 @@
-import { DataOf, DehydrateOptions, DehydratedState, EnsuredQueryHandle, HydrateOptions, InputArgs, InputOf, LoadOptions, PagedQueryFactory, Query, QueryCache, QueryFactory, QueryHandle } from "@raf-query/core";
+import { DataOf, DehydrateOptions, DehydratedState, HydrateOptions, InputArgs, InputOf, LoadOptions, PagedQueryFactory, Query, QueryCache, QueryFactory, QueryHandle, QueryHandleWithData } from "@raf-query/core";
 import { Effect, Layer } from "effect";
 //#region src/client.d.ts
 export interface QueryClientConfig<TServices = never> extends QueryCache.Config {
@@ -47,22 +47,21 @@ export declare class QueryClient<TServices = never> {
    */
   prefetch<TFactory extends QueryFactory<TServices>>(factory: TFactory, ...args: InputArgs<TFactory>): QueryHandle<TFactory>;
   /**
-   * Start a query and wait for it on a cache miss. Rejects if that request
-   * fails. Stale cached data resolves immediately and revalidates in the
-   * browser. The handle is marked `ensured`, so `useQuery` returns its data
-   * directly.
+   * {@link fetch} without waiting on stale data: start a query and wait for
+   * it on a cache miss. Stale cached data resolves immediately and
+   * revalidates in the browser. Rejects if that request fails.
    */
-  ensure<TFactory extends QueryFactory<TServices>>(factory: TFactory, ...args: InputArgs<TFactory>): Promise<EnsuredQueryHandle<TFactory>>;
+  ensure<TFactory extends QueryFactory<TServices>>(factory: TFactory, ...args: InputArgs<TFactory>): Promise<QueryHandleWithData<TFactory>>;
   /** {@link ensure}, loading `options.pages` pages of a paged query. */
-  ensure<TFactory extends PagedQueryFactory<TServices>>(factory: TFactory, input: InputOf<TFactory>, options: LoadOptions): Promise<EnsuredQueryHandle<TFactory>>;
+  ensure<TFactory extends PagedQueryFactory<TServices>>(factory: TFactory, input: InputOf<TFactory>, options: LoadOptions): Promise<QueryHandleWithData<TFactory>>;
   /**
-   * Start a query and resolve to its data. Waits on a cache miss and on
-   * stale data (on the server, only invalidated data), so the data is fresh.
-   * Rejects if that request fails.
+   * Start a query and resolve to a handle holding its data. Waits on a cache
+   * miss and on stale data (on the server, only invalidated data), so the
+   * data is fresh. Rejects if that request fails.
    */
-  fetch<TFactory extends QueryFactory<TServices>>(factory: TFactory, ...args: InputArgs<TFactory>): Promise<DataOf<TFactory>>;
+  fetch<TFactory extends QueryFactory<TServices>>(factory: TFactory, ...args: InputArgs<TFactory>): Promise<QueryHandleWithData<TFactory>>;
   /** {@link fetch}, loading `options.pages` pages of a paged query. */
-  fetch<TFactory extends PagedQueryFactory<TServices>>(factory: TFactory, input: InputOf<TFactory>, options: LoadOptions): Promise<DataOf<TFactory>>;
+  fetch<TFactory extends PagedQueryFactory<TServices>>(factory: TFactory, input: InputOf<TFactory>, options: LoadOptions): Promise<QueryHandleWithData<TFactory>>;
   /**
    * Mark queries stale and refetch the ones being read. Resolves once those
    * refetches settle, so an action stays pending until fresh data is on

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, UseEnsuredQueryResult, 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 UseEnsuredQueryResult, 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/tanstack-router-shared.d.mts

@@ -1,16 +1,17 @@
 import { QueryClient } from "./client.mjs";
-import { DehydrateOptions, DehydratedState, EnsuredQueryHandle, HydrateOptions, QueryHandle } from "@raf-query/core";
+import { DehydrateOptions, DehydratedState, HydrateOptions, QueryHandle } from "@raf-query/core";
 import { AnyRouter } from "@tanstack/react-router";
 //#region src/tanstack-router-shared.d.ts
 declare module "@tanstack/react-router" {
   interface SerializableExtensions {
     /**
-     * Handles are `{ key, input, ensured? }`, which the router's serializer
-     * sends as is. Its type check can't see that on its own: keys are
+     * Handles are `{ key, input, data? }`, which the router's serializer
+     * sends as is (`data` is dehydrated anyway, so it is serializable). Its
+     * type check can't see that on its own: keys are
      * `ReadonlyArray<unknown>`, and the handle type names its factory.
      * So `beforeLoad` can put handles in route context.
      */
-    rafQueryHandle: EnsuredQueryHandle | QueryHandle;
+    rafQueryHandle: QueryHandle;
   }
 }
 export interface RouterIntegrationOptions<TRouter extends AnyRouter> {

package/dist/use-query.d.mts

@@ -1,4 +1,4 @@
-import { DataOf, EnsuredQueryHandle, 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,8 +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`. */
-export type UseEnsuredQueryResult<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>];
+/** {@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:
@@ -89,19 +89,25 @@ export type UseEnsuredQueryResult<TFactory extends QueryFactory, TThrow extends
  * 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` had its data loaded before the route rendered, so
- * the hook returns the data (or `Result`) itself:
+ * 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);
  * ```
  *
- * If that entry has lost its data since (garbage-collected, `reset`), the
- * hook suspends until it is refetched.
+ * 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: EnsuredQueryHandle<TFactory>, options?: UseQueryOptions & UseQueryThrowOptions<TFactory> & {
+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;
-}): UseEnsuredQueryResult<TFactory, 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

@@ -87,12 +87,14 @@ function useQuery(factory, handle, options = {}) {
 	]);
 	QueryObserver.trackProp(observer, "promise");
 	const controls = withPromiseCommands(QueryObserver.trackResult(observer, result));
-	if (!(options.throwOnError ?? client.throwOnError)) {
+	const throwOnError = options.throwOnError ?? client.throwOnError;
+	const withData = "data" in handle;
+	if (!throwOnError) {
 		const resultPromise = asResultThenable(result.promise);
-		if (handle.ensured === true) return [use(resultPromise), controls];
+		if (withData) return [use(resultPromise), controls];
 		return [resultPromise, controls];
 	}
-	if (handle.ensured === true) return [use(result.promise), 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.7.12",
+  "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.7.12"
+    "@raf-query/core": "0.9.0"
   },
   "peerDependencies": {
     "@tanstack/react-router": "^1.170.0",