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

@@ -1,5 +1,5 @@
 import { QueryKey } from "./key.mjs";
-import { DataOf, InputArgs, InputOf, LoadOptions, QueryBehavior, QueryFactory, QueryHandle } from "./options.mjs";
+import { DataOf, EnsuredQueryHandle, InputArgs, InputOf, LoadOptions, QueryBehavior, QueryFactory, QueryHandle } from "./options.mjs";
 import { Query, QueryState } from "./query.mjs";
 import { Effect, Stream } from "effect";
 //#region src/client.d.ts
@@ -36,7 +36,7 @@ export type LoadArgs<TFactory extends QueryFactory> = InputArgs<TFactory> | [inp
 export type Updater<TData> = TData | ((previous: TData | undefined) => TData);
 /** Effect-returning twins of the client's async methods. */
 export interface QueryClientEffect {
-  ensure<TFactory extends QueryFactory>(factory: TFactory, ...args: LoadArgs<TFactory>): Effect.Effect<QueryHandle<TFactory>, unknown>;
+  ensure<TFactory extends QueryFactory>(factory: TFactory, ...args: LoadArgs<TFactory>): Effect.Effect<EnsuredQueryHandle<TFactory>, unknown>;
   fetch<TFactory extends QueryFactory>(factory: TFactory, ...args: LoadArgs<TFactory>): Effect.Effect<DataOf<TFactory>, unknown>;
   invalidate<TFactory extends QueryFactory>(factory: TFactory, ...args: InputArgs<TFactory>): Effect.Effect<void>;
   invalidate(filter: QueryFilter): Effect.Effect<void>;
@@ -69,9 +69,10 @@ export declare class QueryClient {
   prefetch<TFactory extends QueryFactory>(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.
+   * fails. Stale cached data resolves immediately and revalidates. The
+   * handle is marked `ensured`, so `useQuery` returns its data directly.
    */
-  ensure<TFactory extends QueryFactory>(factory: TFactory, ...args: LoadArgs<TFactory>): Promise<QueryHandle<TFactory>>;
+  ensure<TFactory extends QueryFactory>(factory: TFactory, ...args: LoadArgs<TFactory>): Promise<EnsuredQueryHandle<TFactory>>;
   /** Like `ensure`, but resolves to the data. */
   fetch<TFactory extends QueryFactory>(factory: TFactory, ...args: LoadArgs<TFactory>): Promise<DataOf<TFactory>>;
   /**

package/dist/client.mjs

@@ -21,6 +21,12 @@ function typed(entry) {
 function handleOf(entry) {
 	return entry.handle;
 }
+function ensuredHandleOf(entry) {
+	return {
+		...handleOf(entry),
+		ensured: true
+	};
+}
 /**
 * The query cache. Create one per request on the server and one per browser
 * tab.
@@ -95,12 +101,13 @@ var QueryClient = class {
 	}
 	/**
 	* Start a query and wait for it on a cache miss. Rejects if that request
-	* fails. Stale cached data resolves immediately and revalidates.
+	* fails. Stale cached data resolves immediately and revalidates. The
+	* handle is marked `ensured`, so `useQuery` returns its data directly.
 	*/
 	async ensure(factory, ...args) {
 		const entry = this.#build(factory, args[0]);
 		await this.#load(entry, args[1]?.pages);
-		return handleOf(entry);
+		return ensuredHandleOf(entry);
 	}
 	/** Like `ensure`, but resolves to the data. */
 	async fetch(factory, ...args) {

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, 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 { 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, 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 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/options.d.mts

@@ -103,15 +103,27 @@ export type LoadOptions<TFactory extends QueryFactory> = IsPaged<TFactory> exten
   readonly pages?: number;
 } : never;
 declare const factoryType: unique symbol;
-/**
- * The serializable reference a loader or server component hands to the
- * component that reads the query. It holds no data and no functions.
- */
-export interface QueryHandle<TFactory extends QueryFactory = QueryFactory> {
+interface HandleFields<TFactory extends QueryFactory> {
   /** Type-only: ties the handle to its factory. Never present at runtime. */
   readonly [factoryType]?: TFactory;
   /** The factory's input; `unknown` on a handle of no particular factory. */
   readonly input: QueryFactory extends TFactory ? unknown : InputOf<TFactory>;
   readonly key: QueryKey;
 }
+/**
+ * The serializable reference a loader or server component hands to the
+ * component that reads the query. It holds no data and no functions.
+ */
+export interface QueryHandle<TFactory extends QueryFactory = QueryFactory> extends HandleFields<TFactory> {
+  readonly ensured?: false;
+}
+/**
+ * A handle from `ensure`: its data was loaded before the handle was
+ * returned, so `useQuery` returns the data rather than a promise. Not
+ * assignable to {@link QueryHandle}, so a prop typed for one can't receive
+ * the other.
+ */
+export interface EnsuredQueryHandle<TFactory extends QueryFactory = QueryFactory> extends HandleFields<TFactory> {
+  readonly ensured: true;
+}
 //#endregion

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.12",
+  "version": "0.0.14",
   "description": "Framework-agnostic core of raf-query, a render-as-you-fetch query library",
   "keywords": [
     "query",