@raf-query/react 0.7.12 → 0.8.0

package/CHANGELOG.md

@@ -1,15 +1,29 @@
 # Changelog
 
+## [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

@@ -19,6 +19,7 @@ npm install @raf-query/react
 
 ```tsx
 import { queryOptions, useQuery } from "@raf-query/react";
+import { use } from "react";
 
 export function postQuery(input: { slug: string }) {
 	return queryOptions({
@@ -40,7 +41,7 @@ export const Route = createFileRoute("/posts/$slug")({
 // …and the component reads it.
 function PostPage() {
 	const [post] = useQuery(postQuery, Route.useLoaderData().post);
-	return <h1>{post.title}</h1>;
+	return <h1>{use(post).title}</h1>;
 }
 ```
 

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, 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 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, QueryKey, QueryObserver } from "@raf-query/core";
 import { Result } from "effect";
 //#region src/use-query.d.ts
 /** `refetchInterval`, `refetchOnWindowFocus`, `refetchOnReconnect`, `whilePending`. */
@@ -63,8 +63,6 @@ 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>];
 /**
  * Read the query a handle points at. Returns a promise to unwrap with
  * `use()` and the query's controls:
@@ -89,19 +87,11 @@ 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:
- *
- * ```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.
+ * 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`).
  */
-export declare function useQuery<TFactory extends QueryFactory, const TThrow extends boolean | undefined = undefined>(factory: TFactory, handle: EnsuredQueryHandle<TFactory>, options?: UseQueryOptions & UseQueryThrowOptions<TFactory> & {
-  readonly throwOnError?: TThrow;
-}): UseEnsuredQueryResult<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 { use, useEffect, useState, useSyncExternalStore } from "react";
+import { useEffect, useState, useSyncExternalStore } from "react";
 //#region src/use-query.ts
 function queryFor(client, factory, input) {
 	const args = [input];
@@ -87,12 +87,7 @@ function useQuery(factory, handle, options = {}) {
 	]);
 	QueryObserver.trackProp(observer, "promise");
 	const controls = withPromiseCommands(QueryObserver.trackResult(observer, result));
-	if (!(options.throwOnError ?? client.throwOnError)) {
-		const resultPromise = asResultThenable(result.promise);
-		if (handle.ensured === true) return [use(resultPromise), controls];
-		return [resultPromise, controls];
-	}
-	if (handle.ensured === true) return [use(result.promise), controls];
+	if (!(options.throwOnError ?? client.throwOnError)) return [asResultThenable(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.8.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.8.0"
   },
   "peerDependencies": {
     "@tanstack/react-router": "^1.170.0",