@raf-query/react 0.0.13 → 0.0.15

package/CHANGELOG.md

@@ -1,10 +1,20 @@
 # Changelog
 
+## [0.0.15](https://github.com/KATT/raf-query/compare/0.0.14...0.0.15) (2026-10-12)
+
+* **agent-docs:** replace local ~/dev path with upstream React link ([#17](https://github.com/KATT/raf-query/issues/17)) ([79c0314](https://github.com/KATT/raf-query/commit/79c031475c3ed62ce5a07fb91d68733534e452b3))
+
+## [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))
+- 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)
 

package/README.md

@@ -189,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`.
 
@@ -304,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`
 
@@ -557,18 +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                                      |
-| `EnsuredQueryHandle<TFactory>`                 | Handle type for props fed by `ensure`                      |
-| `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/use-query.d.mts

@@ -1,19 +1,7 @@
-import { DataOf, EnsuredQueryHandle, 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. */
@@ -61,6 +49,8 @@ export type UseEnsuredQueryResult<TFactory extends QueryFactory> = readonly [dat
  *
  * 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:

package/dist/use-query.mjs

@@ -1,71 +1,42 @@
 "use client";
 import { useQueryClient } from "./provider.mjs";
 import { unsafeCast } from "./cast.mjs";
-import { use, 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]);
-}
 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
-	};
-	if (handle.ensured === true) return unsafeCast([use(shown.promise), controls]);
-	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.13",
+  "version": "0.0.15",
   "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.13",
+    "@raf-query/core": "0.0.15",
     "effect": "^4.0.1"
   },
   "peerDependencies": {