@raf-query/core 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/index.d.mts

@@ -1,7 +1,8 @@
 import { Settled, allKeyed } from "./all-keyed.mjs";
 import { QueryKey, hashKey, matchesKey } from "./key.mjs";
 import { AnyQueryOptions, DataOf, EnsuredQueryHandle, InfiniteData, InfiniteQueryOptions, InputArgs, InputOf, IsPaged, LoadOptions, PageFunctionContext, PageOf, QueryBehavior, QueryFactory, QueryFnResult, QueryFunctionContext, QueryHandle, QueryOptions, RetryPolicy, infiniteQueryOptions, queryOptions } from "./options.mjs";
-import { CancelledError, FetchRequest, Query, QueryObserver, QueryState } from "./query.mjs";
+import { CancelledError, FetchRequest, Query, QueryState, SubscribeOptions } from "./query.mjs";
 import { CacheEvent, LoadArgs, QueryClient, QueryClientConfig, QueryClientEffect, QueryFilter, Updater } from "./client.mjs";
 import { DehydrateOptions, DehydratedQuery, DehydratedState, HydrateOptions, canDehydrate, dehydrate, dehydrateQuery, hydrate } from "./hydration.mjs";
-export { type AnyQueryOptions, type CacheEvent, CancelledError, type DataOf, type DehydrateOptions, type DehydratedQuery, type DehydratedState, type EnsuredQueryHandle, type FetchRequest, type HydrateOptions, type InfiniteData, type InfiniteQueryOptions, type InputArgs, type InputOf, type IsPaged, type LoadArgs, type LoadOptions, type PageFunctionContext, type PageOf, type Query, type QueryBehavior, QueryClient, type QueryClientConfig, type QueryClientEffect, type QueryFactory, type QueryFilter, type QueryFnResult, type QueryFunctionContext, type QueryHandle, type QueryKey, type QueryObserver, type QueryOptions, type QueryState, type RetryPolicy, type Settled, type Updater, allKeyed, canDehydrate, dehydrate, dehydrateQuery, hashKey, hydrate, infiniteQueryOptions, matchesKey, queryOptions };
+import { QueryObserver, QueryObserverOptions, QueryObserverResult } from "./observer.mjs";
+export { type AnyQueryOptions, type CacheEvent, CancelledError, type DataOf, type DehydrateOptions, type DehydratedQuery, type DehydratedState, type EnsuredQueryHandle, type FetchRequest, type HydrateOptions, type InfiniteData, type InfiniteQueryOptions, type InputArgs, type InputOf, type IsPaged, type LoadArgs, type LoadOptions, type PageFunctionContext, type PageOf, type Query, type QueryBehavior, QueryClient, type QueryClientConfig, type QueryClientEffect, type QueryFactory, type QueryFilter, type QueryFnResult, type QueryFunctionContext, type QueryHandle, type QueryKey, QueryObserver, type QueryObserverOptions, type QueryObserverResult, type QueryOptions, type QueryState, type RetryPolicy, type Settled, type SubscribeOptions, type Updater, allKeyed, canDehydrate, dehydrate, dehydrateQuery, hashKey, hydrate, infiniteQueryOptions, matchesKey, queryOptions };

package/dist/index.mjs

@@ -4,4 +4,5 @@ import { infiniteQueryOptions, queryOptions } from "./options.mjs";
 import { CancelledError } from "./query.mjs";
 import { QueryClient } from "./client.mjs";
 import { canDehydrate, dehydrate, dehydrateQuery, hydrate } from "./hydration.mjs";
-export { CancelledError, QueryClient, allKeyed, canDehydrate, dehydrate, dehydrateQuery, hashKey, hydrate, infiniteQueryOptions, matchesKey, queryOptions };
+import { QueryObserver } from "./observer.mjs";
+export { CancelledError, QueryClient, QueryObserver, allKeyed, canDehydrate, dehydrate, dehydrateQuery, hashKey, hydrate, infiniteQueryOptions, matchesKey, queryOptions };

package/dist/observer.d.mts

@@ -0,0 +1,82 @@
+import { QueryKey } from "./key.mjs";
+import { QueryFactory } from "./options.mjs";
+import { Query } from "./query.mjs";
+//#region src/observer.d.ts
+/** How one reader observes its query. */
+export interface QueryObserverOptions {
+  /** Refetch on this interval (ms) while subscribed 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 show while the query has no data yet:
+   * - `"suspend"` (default): the result's promise is the query's pending one.
+   * - `"previous"`: keep the last observed query's data, with `isPrevious`.
+   */
+  readonly whilePending?: "previous" | "suspend";
+}
+/** What a reader sees of its query. Replaced, never mutated, on every change. */
+export interface QueryObserverResult<TData = unknown> {
+  /** Error of the last failed request. Existing data stays readable. */
+  readonly error: unknown;
+  fetchNextPage(): Promise<void>;
+  fetchPreviousPage(): Promise<void>;
+  /** Stable string form of the observed query's key. */
+  readonly hash: string;
+  readonly hasNextPage: boolean;
+  readonly hasPreviousPage: boolean;
+  /** Input of the data in `promise`; differs from the query's while `isPrevious`. */
+  readonly input: unknown;
+  /** A request is in flight: first load, new input, or background refetch. */
+  readonly isFetching: boolean;
+  readonly isFetchingNextPage: boolean;
+  readonly isFetchingPreviousPage: boolean;
+  /** No data yet for the observed query. */
+  readonly isPending: boolean;
+  /** `promise` holds a previous query's data (`whilePending: "previous"`). */
+  readonly isPrevious: boolean;
+  /** The data is older than `staleTime`, or was invalidated. */
+  readonly isStale: boolean;
+  /** Key of the data in `promise`; differs from the query's while `isPrevious`. */
+  readonly key: QueryKey;
+  /** Settles with the data to show; see `QueryState.promise`. */
+  readonly promise: Promise<TData>;
+  refetch(): Promise<void>;
+  /** When the data in `promise` was fetched (ms since epoch); `0` before that. */
+  readonly updatedAt: number;
+}
+type ResultKey = keyof QueryObserverResult;
+/**
+ * One reader of one query at a time, like TanStack Query's `QueryObserver`:
+ * it derives the reader's result from the query's state, keeps a previous
+ * query's data for `whilePending: "previous"`, runs `refetchInterval`, and
+ * notifies its listeners only when a result property they read changed
+ * (see {@link QueryObserver.trackResult}). Bindings create one per hook.
+ */
+export declare class QueryObserver<TData = unknown, TFactory extends QueryFactory = QueryFactory> {
+  #private;
+  constructor(query: Query<TData, TFactory>, options?: QueryObserverOptions);
+  /**
+   * The result for `query` with `options` right now, without switching to
+   * it. Bindings call this during render, before `setOptions` commits.
+   */
+  getOptimisticResult(query: Query<TData, TFactory>, options: QueryObserverOptions): QueryObserverResult<TData>;
+  getCurrentResult: () => QueryObserverResult<TData>;
+  /** Observe `query` with `options` from now on. */
+  setOptions(query: Query<TData, TFactory>, options: QueryObserverOptions): void;
+  /** Listen for result changes. The first listener subscribes to the query. */
+  subscribe: (listener: () => void) => (() => void);
+  /**
+   * Wrap `result` so that reading a property marks it tracked. Once any
+   * property is tracked, listeners are only notified when a tracked one
+   * changes.
+   */
+  trackResult<TResult extends QueryObserverResult<TData>>(result: TResult): TResult;
+  /** Mark `name` as read, for bindings that track access themselves. */
+  trackProp(name: ResultKey): void;
+  /** Recompute the result, and notify listeners if a tracked property changed. */
+  updateResult(): void;
+}
+//#endregion

package/dist/observer.mjs

@@ -0,0 +1,167 @@
+//#region src/observer.ts
+const resultKeys = {
+	error: true,
+	fetchNextPage: true,
+	fetchPreviousPage: true,
+	hash: true,
+	hasNextPage: true,
+	hasPreviousPage: true,
+	input: true,
+	isFetching: true,
+	isFetchingNextPage: true,
+	isFetchingPreviousPage: true,
+	isPending: true,
+	isPrevious: true,
+	isStale: true,
+	key: true,
+	promise: true,
+	refetch: true,
+	updatedAt: true
+};
+function isResultKey(name) {
+	return typeof name === "string" && Object.hasOwn(resultKeys, name);
+}
+function shallowEqual(a, b) {
+	for (const name of Object.keys(resultKeys)) if (isResultKey(name) && a[name] !== b[name]) return false;
+	return true;
+}
+/**
+* One reader of one query at a time, like TanStack Query's `QueryObserver`:
+* it derives the reader's result from the query's state, keeps a previous
+* query's data for `whilePending: "previous"`, runs `refetchInterval`, and
+* notifies its listeners only when a result property they read changed
+* (see {@link QueryObserver.trackResult}). Bindings create one per hook.
+*/
+var QueryObserver = class {
+	#current;
+	#interval;
+	#lastWithData;
+	#listeners = /* @__PURE__ */ new Set();
+	#options;
+	#query;
+	#trackedProps = /* @__PURE__ */ new Set();
+	#unsubscribe;
+	constructor(query, options = {}) {
+		this.#query = query;
+		this.#options = options;
+		this.#current = this.#createResult(query, options);
+		this.updateResult();
+	}
+	/**
+	* The result for `query` with `options` right now, without switching to
+	* it. Bindings call this during render, before `setOptions` commits.
+	*/
+	getOptimisticResult(query, options) {
+		const result = this.#createResult(query, options);
+		if (!shallowEqual(this.#current, result)) this.#current = result;
+		return result;
+	}
+	getCurrentResult = () => this.#current;
+	/** Observe `query` with `options` from now on. */
+	setOptions(query, options) {
+		const previous = this.#query;
+		const previousInterval = this.#options.refetchInterval;
+		this.#query = query;
+		this.#options = options;
+		if (this.#listeners.size > 0) {
+			if (query !== previous) {
+				this.#unsubscribe?.();
+				this.#unsubscribe = this.#subscribeToQuery();
+			}
+			if (query !== previous || options.refetchInterval !== previousInterval) this.#startInterval();
+		}
+		this.updateResult();
+	}
+	/** Listen for result changes. The first listener subscribes to the query. */
+	subscribe = (listener) => {
+		this.#listeners.add(listener);
+		if (this.#listeners.size === 1) {
+			this.#unsubscribe = this.#subscribeToQuery();
+			this.#startInterval();
+			this.updateResult();
+		}
+		return () => {
+			if (!this.#listeners.delete(listener) || this.#listeners.size > 0) return;
+			this.#unsubscribe?.();
+			this.#unsubscribe = void 0;
+			clearInterval(this.#interval);
+		};
+	};
+	/**
+	* Wrap `result` so that reading a property marks it tracked. Once any
+	* property is tracked, listeners are only notified when a tracked one
+	* changes.
+	*/
+	trackResult(result) {
+		return new Proxy(result, { get: (target, name, receiver) => {
+			if (isResultKey(name)) this.trackProp(name);
+			return Reflect.get(target, name, receiver);
+		} });
+	}
+	/** Mark `name` as read, for bindings that track access themselves. */
+	trackProp(name) {
+		this.#trackedProps.add(name);
+	}
+	/** Recompute the result, and notify listeners if a tracked property changed. */
+	updateResult() {
+		const previous = this.#current;
+		const next = this.#createResult(this.#query, this.#options);
+		if (this.#query.getState().hasData) this.#lastWithData = this.#query;
+		if (shallowEqual(previous, next)) return;
+		this.#current = next;
+		if (this.#shouldNotify(previous, next)) for (const listener of this.#listeners) listener();
+	}
+	#shouldNotify(previous, next) {
+		if (this.#trackedProps.size === 0) return true;
+		for (const name of this.#trackedProps) if (previous[name] !== next[name]) return true;
+		return false;
+	}
+	#subscribeToQuery() {
+		const options = () => this.#options;
+		return this.#query.subscribe(() => this.updateResult(), {
+			get refetchOnReconnect() {
+				return options().refetchOnReconnect;
+			},
+			get refetchOnWindowFocus() {
+				return options().refetchOnWindowFocus;
+			}
+		});
+	}
+	#startInterval() {
+		clearInterval(this.#interval);
+		this.#interval = void 0;
+		const interval = this.#options.refetchInterval;
+		if (interval === void 0 || !Number.isFinite(interval) || interval <= 0) return;
+		this.#interval = setInterval(() => {
+			if (!("document" in globalThis) || document.visibilityState !== "hidden") this.#query.refetch();
+		}, interval);
+	}
+	#createResult(query, options) {
+		const state = query.getState();
+		const last = this.#lastWithData;
+		const previous = options.whilePending === "previous" && !state.hasData && state.status !== "error" && last !== void 0 && last.hash !== query.hash ? last : void 0;
+		const shown = previous ?? query;
+		const shownState = previous ? previous.getState() : state;
+		return {
+			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,
+			promise: shownState.promise,
+			refetch: query.refetch,
+			updatedAt: shownState.updatedAt
+		};
+	}
+};
+//#endregion
+export { QueryObserver };

package/dist/query.d.mts

@@ -28,7 +28,7 @@ export interface QueryState<TData> {
   readonly updatedAt: number;
 }
 /** Per-reader preferences, registered with {@link Query.subscribe}. */
-export interface QueryObserver {
+export interface SubscribeOptions {
   readonly refetchOnReconnect?: boolean;
   readonly refetchOnWindowFocus?: boolean;
 }
@@ -77,7 +77,7 @@ export interface Query<TData = unknown, TFactory extends QueryFactory = QueryFac
    */
   reset(): Promise<void>;
   /** Listen for state changes. Subscribed entries count as read. */
-  subscribe(listener: () => void, observer?: QueryObserver): () => void;
+  subscribe(listener: () => void, options?: SubscribeOptions): () => void;
 }
 /** Thrown into a request's awaiters when the cache is cleared mid-request. */
 export declare class CancelledError extends Error {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@raf-query/core",
-  "version": "0.0.13",
+  "version": "0.0.15",
   "description": "Framework-agnostic core of raf-query, a render-as-you-fetch query library",
   "keywords": [
     "query",