@raf-query/react 0.0.11 → 0.0.13

package/CHANGELOG.md

@@ -1,10 +1,20 @@
 # Changelog
 
+## [0.0.13](https://github.com/KATT/raf-query/compare/0.0.12...0.0.13) (2026-10-12)
+
+### Features
+
+* useQuery returns data for handles from ensure ([#16](https://github.com/KATT/raf-query/issues/16)) ([a50b8fd](https://github.com/KATT/raf-query/commit/a50b8fdc51b952341377d4b55f25ebb6b21d39e1))
+
+## [0.0.12](https://github.com/KATT/raf-query/compare/0.0.11...0.0.12) (2026-10-12)
+
+- **examples:** move the shared db and ui packages into examples/.shared ([#14](https://github.com/KATT/raf-query/issues/14)) ([fccdc7b](https://github.com/KATT/raf-query/commit/fccdc7bb8075ce2fb0cdbe07b26b36f2ace2bd9c))
+
 ## [0.0.11](https://github.com/KATT/raf-query/compare/0.0.10...0.0.11) (2026-10-12)
 
 ### Features
 
-* **core:** structurally share new data with the old (structuralSharing) ([#15](https://github.com/KATT/raf-query/issues/15)) ([bf4392a](https://github.com/KATT/raf-query/commit/bf4392a56936ead6fb8b2726981cb19dadf51304))
+- **core:** structurally share new data with the old (structuralSharing) ([#15](https://github.com/KATT/raf-query/issues/15)) ([bf4392a](https://github.com/KATT/raf-query/commit/bf4392a56936ead6fb8b2726981cb19dadf51304))
 
 ## [0.0.10](https://github.com/KATT/raf-query/compare/0.0.9...0.0.10) (2026-10-12)
 

package/README.md

@@ -72,11 +72,11 @@ The factory is the only place a query is declared paged. Every other API — `pr
 
 All three verbs live on the query client and accept a factory plus its input.
 
-| Call                              | Returns                | Blocks? | Use for                                                    |
-| --------------------------------- | ---------------------- | ------- | ---------------------------------------------------------- |
-| `qc.prefetch(factory, input)`     | `QueryHandle`          | No      | Data the route can render without; it streams in           |
-| `await qc.ensure(factory, input)` | `Promise<QueryHandle>` | Yes     | Data the route must not render without                     |
-| `await qc.fetch(factory, input)`  | `Promise<Data>`        | Yes     | Rendering in a server component, or building another input |
+| Call                              | Returns                       | Blocks? | Use for                                                                |
+| --------------------------------- | ----------------------------- | ------- | ---------------------------------------------------------------------- |
+| `qc.prefetch(factory, input)`     | `QueryHandle`                 | No      | Data the route can render without; it streams in                       |
+| `await qc.ensure(factory, input)` | `Promise<EnsuredQueryHandle>` | Yes     | Data the route must not render without; `useQuery` returns it directly |
+| `await qc.fetch(factory, input)`  | `Promise<Data>`               | Yes     | Rendering in a server component, or building another input             |
 
 ```tsx
 // TanStack Start
@@ -125,9 +125,16 @@ interface QueryHandle<TFactory> {
 	readonly key: QueryKey; // ["post", "hello"]
 	readonly input: InputOf<TFactory>; // { slug: "hello" }
 }
+
+// From `ensure`: the route waited for the data.
+interface EnsuredQueryHandle<TFactory> {
+	readonly key: QueryKey;
+	readonly input: InputOf<TFactory>;
+	readonly ensured: true;
+}
 ```
 
-Handles hold no data and no functions. Data reaches the client cache through the [hydration stream](#ssr-and-hydration), so loader data stays tiny and each query is serialized once. The loader's return value lists exactly which queries a route started, and a handle from `ensure` versus `prefetch` shows whether the route waited for it.
+Handles hold no data and no functions. Data reaches the client cache through the [hydration stream](#ssr-and-hydration), so loader data stays tiny and each query is serialized once. The loader's return value lists exactly which queries a route started, and its types show which ones the route waited for: `useQuery` returns the data for an `EnsuredQueryHandle` and a promise for a `QueryHandle`. The two aren't assignable to each other, so type a prop with the one its loader returns.
 
 ## Reading queries
 
@@ -135,17 +142,20 @@ Handles hold no data and no functions. Data reaches the client cache through the
 
 ```ts
 const [promise, controls] = useQuery(factory, handle, options?);
+const [data, controls] = useQuery(factory, ensuredHandle, options?);
 ```
 
 `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.
 
+A handle from `ensure` had its data loaded before the route rendered, so `useQuery` returns the data itself. If the entry has lost that data since (it was garbage-collected while the router kept the loader data, or `reset`), the hook suspends until it is refetched.
+
 ```tsx
 function PostPage() {
 	const loaderData = Route.useLoaderData();
-	const [postPromise, postState] = useQuery(postQuery, loaderData.post);
-	const post = use(postPromise);
+	// `post` came from `qc.ensure`, `comments` from `qc.prefetch`.
+	const [post, postState] = useQuery(postQuery, loaderData.post);
 
 	return (
 		<article>
@@ -267,6 +277,7 @@ Either way, an input that's already cached renders immediately. A component that
 To show a skeleton instead, for instance when moving between unrelated posts, give the Suspense boundary the query's key. React treats it as new content and shows its fallback, even inside a transition:
 
 ```tsx
+// This loader prefetches the post instead of ensuring it.
 const [postPromise, postState] = useQuery(postQuery, loaderData.post);
 
 return (
@@ -282,10 +293,10 @@ In Next.js the same rules apply: read `searchParams` in the page, `prefetch` wit
 
 ### Passing promises down
 
-A component can call the hook and hand the promise to a child, so only the child suspends:
+A component can call the hook with a prefetched handle and hand the promise to a child, so only the child suspends:
 
 ```tsx
-const [postPromise] = useQuery(postQuery, loaderData.post);
+const [postPromise] = useQuery(postQuery, loaderData.post); // from `qc.prefetch`
 return (
 	<Suspense fallback={<Spinner />}>
 		<PostBody post={postPromise} />
@@ -435,6 +446,7 @@ export default async function Page(props: {
 - `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. 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.
+- `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.
 
 #### Server-only queries
@@ -555,6 +567,7 @@ Query options, accepted by `queryOptions`, `infiniteQueryOptions` and `config.de
 | `hashKey(key)`, `matchesKey(key, prefix)`      | Key helpers                                                |
 | `CancelledError`                               | Rejection of a request cancelled by `clear()` or a restart |
 | `QueryHandle<TFactory>`                        | Handle type for props                                      |
+| `EnsuredQueryHandle<TFactory>`                 | Handle type for props fed by `ensure`                      |
 | `DataOf<TFactory>`, `InputOf<TFactory>`        | A factory's data and input types                           |
 
 `@raf-query/react` (plus all of the above):

package/dist/index.d.mts

@@ -1,5 +1,5 @@
 import { QueryClientProvider, useQueryClient } from "./provider.mjs";
-import { PagingControls, QueryControls, UseQueryControls, UseQueryOptions, UseQueryResult, useQuery } from "./use-query.mjs";
+import { PagingControls, QueryControls, UseEnsuredQueryResult, 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 };
+export { type PagingControls, QueryClientProvider, type QueryControls, type UseEnsuredQueryResult, type UseQueryControls, type UseQueryOptions, type UseQueryResult, useQuery, useQueryClient, useWaterfall };

package/dist/use-query.d.mts

@@ -1,4 +1,4 @@
-import { DataOf, InputOf, IsPaged, QueryClient, QueryFactory, QueryHandle, QueryKey } from "@raf-query/core";
+import { DataOf, EnsuredQueryHandle, 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. */
@@ -48,6 +48,8 @@ export interface PagingControls {
 }
 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>];
+/** {@link useQuery}'s result for a handle from `ensure`. */
+export type UseEnsuredQueryResult<TFactory extends QueryFactory> = readonly [data: DataOf<TFactory>, controls: UseQueryControls<TFactory>];
 /**
  * Read the query a handle points at. Returns a promise to unwrap with
  * `use()` and the query's controls:
@@ -59,6 +61,17 @@ export type UseQueryResult<TFactory extends QueryFactory> = readonly [promise: P
  *
  * 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.
+ *
+ * A handle from `ensure` had its data loaded before the route rendered, so
+ * the hook returns the data 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.
  */
+export declare function useQuery<TFactory extends QueryFactory>(factory: TFactory, handle: EnsuredQueryHandle<TFactory>, options?: UseQueryOptions): UseEnsuredQueryResult<TFactory>;
 export declare function useQuery<TFactory extends QueryFactory>(factory: TFactory, handle: QueryHandle<TFactory>, options?: UseQueryOptions): UseQueryResult<TFactory>;
 //#endregion

package/dist/use-query.mjs

@@ -1,7 +1,7 @@
 "use client";
 import { useQueryClient } from "./provider.mjs";
 import { unsafeCast } from "./cast.mjs";
-import { useCallback, useEffect, useState, useSyncExternalStore } from "react";
+import { use, useCallback, useEffect, useState, useSyncExternalStore } from "react";
 //#region src/use-query.ts
 function queryFor(client, factory, input) {
 	const args = [input];
@@ -16,18 +16,6 @@ function useRefetchInterval(query, 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();
@@ -76,6 +64,7 @@ function useQuery(factory, handle, options = {}) {
 		refetch: query.refetch,
 		updatedAt: shown.updatedAt
 	};
+	if (handle.ensured === true) return unsafeCast([use(shown.promise), controls]);
 	return unsafeCast([shown.promise, controls]);
 }
 //#endregion

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@raf-query/react",
-  "version": "0.0.11",
+  "version": "0.0.13",
   "description": "React bindings for raf-query, a render-as-you-fetch query library",
   "keywords": [
     "query",
@@ -40,7 +40,7 @@
     "./tanstack-router": "./dist/tanstack-router.mjs"
   },
   "dependencies": {
-    "@raf-query/core": "0.0.11",
+    "@raf-query/core": "0.0.13",
     "effect": "^4.0.1"
   },
   "peerDependencies": {