@raf-query/react 0.0.12 → 0.0.14

package/CHANGELOG.md

@@ -1,8 +1,20 @@
 # Changelog
 
+## [0.0.14](https://github.com/KATT/raf-query/compare/0.0.13...0.0.14) (2026-10-12)
+
+### Features
+
+* tracked query results via a core QueryObserver, like TanStack Query ([#13](https://github.com/KATT/raf-query/issues/13)) ([7b99b47](https://github.com/KATT/raf-query/commit/7b99b4704be110c999b41277afd5dac4c515f45f))
+
+## [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))
+- **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)
 

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>
@@ -179,7 +189,7 @@ function PostPage() {
 | `hash`         | Stable string form of the handle's key, for `key` props on Suspense boundaries                                           |
 | `refetch()`    | Refetch now. Returns a promise, so it can be awaited inside a transition or action                                       |
 
-When the cache updates — refetch, invalidation, `setData` — the hook returns a new, pre-resolved promise and the component re-renders without suspending. New data is structurally shared with the old: objects and arrays that are deeply equal keep their identity, and a refetch that returns equal data keeps the same promise, so nothing re-renders. When the **first** load fails, the promise rejects and `use()` throws to the nearest error boundary. Resetting that boundary refetches the query.
+When the cache updates — refetch, invalidation, `setData` — the hook returns a new, pre-resolved promise and the component re-renders without suspending. New data is structurally shared with the old: objects and arrays that are deeply equal keep their identity, and a refetch that returns equal data keeps the same promise, so nothing re-renders. Controls are tracked: reading `controls.isFetching` subscribes the component to `isFetching`, and a change to a control it never read doesn't re-render it. When the **first** load fails, the promise rejects and `use()` throws to the nearest error boundary. Resetting that boundary refetches the query.
 
 Queries do not refetch on mount. They refetch when a loader starts them again, when invalidated, on window focus or reconnect while stale, on `refetch()`, or on `refetchInterval`.
 
@@ -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} />
@@ -293,7 +304,7 @@ return (
 );
 ```
 
-The parent re-renders when `controls` change. If it only passes the promise down, call the hook in the child instead.
+A component re-renders when the promise changes, and when a control it reads changes. Controls it never reads, like `isFetching` here, don't re-render it, so a parent that only passes the promise down stays put during background refetches.
 
 ## Render-time inputs: `useWaterfall`
 
@@ -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
@@ -545,17 +557,19 @@ Query options, accepted by `queryOptions`, `infiniteQueryOptions` and `config.de
 
 `@raf-query/core`:
 
-| 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                           |
+| 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                                                      |
+| `QueryObserver`                                | One reader's view of a query, with tracked results; for bindings |
+| `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,19 +1,7 @@
-import { DataOf, InputOf, IsPaged, QueryClient, QueryFactory, QueryHandle, QueryKey } from "@raf-query/core";
+import { DataOf, EnsuredQueryHandle, InputOf, IsPaged, QueryClient, QueryFactory, QueryHandle, QueryKey, QueryObserverOptions } 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";
-}
+/** `refetchInterval`, `refetchOnWindowFocus`, `refetchOnReconnect`, `whilePending`. */
+export type UseQueryOptions = QueryObserverOptions;
 /** The second element of {@link useQuery}'s result. */
 export interface QueryControls<TFactory extends QueryFactory> {
   /** Error of the last failed request. Existing data stays readable. */
@@ -48,6 +36,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 +49,19 @@ 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.
+ * 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 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,82 +1,42 @@
 "use client";
 import { useQueryClient } from "./provider.mjs";
 import { unsafeCast } from "./cast.mjs";
-import { useCallback, useEffect, useState, useSyncExternalStore } from "react";
+import { QueryObserver } from "@raf-query/core";
+import { use, 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 refetchInterval = options.refetchInterval;
 	const refetchOnReconnect = options.refetchOnReconnect;
 	const refetchOnWindowFocus = options.refetchOnWindowFocus;
-	const subscribe = useCallback((onChange) => query.subscribe(onChange, {
-		refetchOnReconnect,
-		refetchOnWindowFocus
-	}), [
+	const whilePending = options.whilePending;
+	const [observer] = useState(() => new QueryObserver(query, options));
+	const result = observer.getOptimisticResult(query, options);
+	useSyncExternalStore(observer.subscribe, observer.getCurrentResult, observer.getCurrentResult);
+	useEffect(() => {
+		observer.setOptions(query, {
+			refetchInterval,
+			refetchOnReconnect,
+			refetchOnWindowFocus,
+			whilePending
+		});
+	}, [
+		observer,
 		query,
+		refetchInterval,
 		refetchOnReconnect,
-		refetchOnWindowFocus
+		refetchOnWindowFocus,
+		whilePending
 	]);
-	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]);
+	observer.trackProp("promise");
+	const controls = observer.trackResult(result);
+	if (handle.ensured === true) return unsafeCast([use(result.promise), controls]);
+	return unsafeCast([result.promise, controls]);
 }
 //#endregion
 export { queryFor, useQuery };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@raf-query/react",
-  "version": "0.0.12",
+  "version": "0.0.14",
   "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.12",
+    "@raf-query/core": "0.0.14",
     "effect": "^4.0.1"
   },
   "peerDependencies": {