@raf-query/core 0.3.1 → 0.4.1

package/CHANGELOG.md

@@ -1,8 +1,22 @@
 # Changelog
 
+## [0.4.1](https://github.com/KATT/raf-query/compare/0.4.0...0.4.1) (2026-10-13)
+
+* one table for the query verbs; fetch and ensure wait alike in server components ([#64](https://github.com/KATT/raf-query/issues/64)) ([13e5549](https://github.com/KATT/raf-query/commit/13e5549e9f1b6df4fe0e8f23f79e1aef7bf94e53))
+
+## [0.4.0](https://github.com/KATT/raf-query/compare/0.3.1...0.4.0) (2026-10-13)
+
+### ⚠ BREAKING CHANGES
+
+- **core:** fetch waits for stale data, as TanStack's fetchQuery does ([#63](https://github.com/KATT/raf-query/issues/63))
+
+### Bug Fixes
+
+- **core:** fetch waits for stale data, as TanStack's fetchQuery does ([#63](https://github.com/KATT/raf-query/issues/63)) ([c9785d5](https://github.com/KATT/raf-query/commit/c9785d5e99c0578c1748de3330823cc0e65f2378))
+
 ## [0.3.1](https://github.com/KATT/raf-query/compare/0.3.0...0.3.1) (2026-10-13)
 
-* teach avoiding dependent queries; frame prefetch vs ensure as loading UX ([#62](https://github.com/KATT/raf-query/issues/62)) ([ec62760](https://github.com/KATT/raf-query/commit/ec627609cbbee9fa4ff0cf568f69964341e27daa))
+- teach avoiding dependent queries; frame prefetch vs ensure as loading UX ([#62](https://github.com/KATT/raf-query/issues/62)) ([ec62760](https://github.com/KATT/raf-query/commit/ec627609cbbee9fa4ff0cf568f69964341e27daa))
 
 ## [0.3.0](https://github.com/KATT/raf-query/compare/0.2.8...0.3.0) (2026-10-13)
 

package/README.md

@@ -118,13 +118,15 @@ declare module "@raf-query/react" {
 
 ## Starting queries
 
-All three verbs live on the query client and accept a factory plus its input.
+All three verbs live on the query client and accept a factory plus its input. They differ in what they return and what they wait for:
 
-| 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 data in a server component                                   |
+| Call                          | Returns                       | Cache miss            | Stale data                                    | TanStack Query                                 |
+| ----------------------------- | ----------------------------- | --------------------- | --------------------------------------------- | ---------------------------------------------- |
+| `qc.prefetch(factory, input)` | `QueryHandle`                 | Starts the request    | Refetches in the background                   | `prefetchQuery`, not awaited                   |
+| `qc.ensure(factory, input)`   | `Promise<EnsuredQueryHandle>` | Waits for the request | Resolves at once, refetches in the background | `ensureQueryData({ revalidateIfStale: true })` |
+| `qc.fetch(factory, input)`    | `Promise<Data>`               | Waits for the request | Waits for the refetch                         | `fetchQuery`                                   |
+
+Fresh cached data is reused by all three, without a request. So `prefetch` never holds anything up, `ensure` holds up only the first visit (returning to a page shows the cached data at once, then fresh data), and `fetch` always returns fresh data, at the cost of a round trip whenever the cache is stale. On the server, data counts as stale only once `invalidate` has marked it (see below).
 
 ```tsx
 // TanStack Start
@@ -227,8 +229,8 @@ When the data really can't be reshaped (a third-party API you don't control), th
 
 Behavior:
 
-- Every verb dedupes against the cache. A fresh entry is reused; a stale entry is refetched in the background.
-- `ensure` and `fetch` wait only on a cache miss. With stale cached data they resolve immediately, so the navigation isn't held up, and revalidate in the background: the page renders the cached data and re-renders when the refetch lands.
+- Every verb dedupes against the cache: a request already in flight for the entry is joined, not repeated.
+- A stale `ensure` doesn't hold up the navigation: the page renders the cached data and re-renders when the background refetch lands. A stale `fetch` in a loader would, so loaders use `ensure`.
 - Loaders run on every navigation (TanStack Router reruns them when its own `staleTime` has passed, `0` by default), so returning to a page shows what's cached at once and then fresh data. With `defaultPreload: "intent"`, also set `defaultPreloadStaleTime: 0`: otherwise the router reuses a hover's preload for 30 seconds instead of running the loader on click, and the query cache never hears about the navigation.
 - On the server, cached data is always reused, whatever `staleTime` says. A server client renders once, so a background refetch could only repeat a request whose result is never shown. Entries marked by `invalidate` still refetch.
 - A failed `prefetch` never throws out of the loader. The error surfaces where the data is read, and is reported to the client's `onError`.
@@ -309,7 +311,7 @@ function PostPage() {
 
 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.
 
-`useQuery` never refetches on mount: whatever started the query decides. Stale data refetches in the background when a loader or server component starts the query again (`prefetch`, `ensure`, `fetch`, or hydrating the server's copy), when `useWaterfall` mounts, when invalidated, on window focus or reconnect, on `refetch()`, or on `refetchInterval`.
+`useQuery` never refetches on mount: whatever started the query decides. Stale data refetches when a loader or server component starts the query again (`prefetch`, `ensure`, `fetch`, or hydrating the server's copy), when `useWaterfall` mounts, when invalidated, on window focus or reconnect, on `refetch()`, or on `refetchInterval`.
 
 For an app-wide indicator, `useIsFetching()` returns how many queries have a request in flight, background refetches included, and re-renders when that changes. Pass a filter to count only some: `useIsFetching({ queryKey: ["comments"] })`. It's `0` on the server and during hydration, so the indicator never appears in server HTML. Outside React, `qc.isFetching(filter?)` returns the same number.
 
@@ -640,8 +642,7 @@ export default async function Page(props: {
 - `HydrationBoundary` sends the request client's entries to the browser cache; pending ones stream as promises through the RSC payload. Render one in each server component that starts queries for client components. Entries already sent in this request are skipped.
 - The browser takes whichever copy is newer, by when it was fetched (`updatedAt`, so server and browser clocks should agree). When it has no data and no request of its own, it resumes the server's pending request. When it has data, or its own request in flight, it waits for the server's instead of fetching again, and takes it if newer. If it keeps its own copy (the server's is older, as in a payload the router replays from its cache on back and forward, or the server's request failed), it refetches it if stale.
 - `QueryProvider` creates one client per server render and one per browser tab. The server render starts no request: a client component reading a query no `HydrationBoundary` sent renders its Suspense fallback on the server, and the query loads in the browser. That boundary renders in the browser through React's error recovery, with the digest Next.js uses for `ssr: false`, so Next.js doesn't report it; other frameworks pass it to `onRecoverableError`. 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 makes one request per query, whatever its `staleTime`.
-- `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.
+- In a server component, `fetch` and `ensure` wait for the same thing: the per-request client only refetches what `invalidate` marked, so cached data is never stale there, and each query makes one request whatever its `staleTime`. They differ only in what they return. `await qc.fetch(...)` the data the server component renders itself, anywhere in the tree. When it 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. The browser runs a page's server actions one at a time, so refetches wait for each other and for any pending mutation. For parallel requests, have the `queryFn` call a [Route Handler](https://nextjs.org/docs/app/api-reference/file-conventions/route), as [`examples/nextjs`](examples/nextjs) does.
 
 #### Server-only queries

package/dist/cache.d.mts

@@ -78,7 +78,11 @@ export interface QueryCache {
   ensure<TFactory extends QueryFactory>(factory: TFactory, ...args: LoadArgs<TFactory>): Effect.Effect<EnsuredQueryHandle<TFactory>, ErrorOf<TFactory> | CancelledError, ServicesOf<TFactory>>;
   /** Cache events from the moment the stream starts. */
   readonly events: Stream.Stream<Event>;
-  /** Like `ensure`, but succeeds with the data. */
+  /**
+   * Start a query and succeed with its data. Waits on a cache miss and on
+   * stale data (on the server, only invalidated data), so the data is fresh.
+   * Fails if that request fails.
+   */
   fetch<TFactory extends QueryFactory>(factory: TFactory, ...args: LoadArgs<TFactory>): Effect.Effect<DataOf<TFactory>, ErrorOf<TFactory> | CancelledError, ServicesOf<TFactory>>;
   /**
    * Cached data for a factory call. `Some(undefined)` when the data itself

package/dist/cache.mjs

@@ -3,7 +3,7 @@ import { Platform } from "./platform.mjs";
 import { unsafeCast } from "./cast.mjs";
 import { listen } from "./listen.mjs";
 import { hashKey, matchesKey } from "./key.mjs";
-import { changes, emit, fetch, invalidate, isObserved, make as make$1, onPlatformEvent, provide, remove, reset, revalidate, setData, setOptions, start } from "./entry.mjs";
+import { changes, emit, fetch, invalidate, isObserved, make as make$1, needsRefetch, onPlatformEvent, provide, remove, reset, revalidate, setData, setOptions, start } from "./entry.mjs";
 import { dehydrateEntries, dehydrateStream, hydrateEntries } from "./hydration.mjs";
 import { optionsFor } from "./options.mjs";
 import { Clock, Context, Effect, Layer, Option, Predicate, RcRef, Stream } from "effect";
@@ -55,11 +55,12 @@ function keyMatcher(filter) {
 	return (entry) => matchesKey(entry.key, prefix);
 }
 /**
-* Waits for an entry's data on a cache miss. Cached data returns at once,
-* and revalidates in the background (see `Entry.revalidate`).
+* Waits for an entry's data on a cache miss, and with `fresh` also while it
+* needs a refetch (see `Entry.needsRefetch`). Otherwise cached data returns at
+* once, and revalidates in the background.
 */
-function load(entry, pages) {
-	if (!entry.state.hasData) return unsafeCast(fetch(entry, { pages }));
+function load(entry, pages, fresh) {
+	if (!entry.state.hasData || fresh && needsRefetch(entry)) return unsafeCast(fetch(entry, { pages }));
 	revalidate(entry);
 	return Effect.succeed(dataOf(entry));
 }
@@ -134,12 +135,12 @@ const make = /*#__PURE__*/ Effect.fnUntraced(function* (config = {}) {
 		}),
 		dehydrate: (options = {}) => Effect.sync(() => dehydrateEntries(state.entries.values(), options)),
 		dehydrateStream: (options = {}) => dehydrateStream(() => state.entries.values(), subscribeUnsafe, options),
-		ensure: (factory, ...args) => Effect.flatMap(buildFor(factory, args[0]), (entry) => load(entry, args[1]?.pages).pipe(Effect.as({
+		ensure: (factory, ...args) => Effect.flatMap(buildFor(factory, args[0]), (entry) => load(entry, args[1]?.pages, false).pipe(Effect.as({
 			...handleOf(entry),
 			ensured: true
 		}))),
 		events: listen(subscribeUnsafe),
-		fetch: (factory, ...args) => Effect.flatMap(buildFor(factory, args[0]), (entry) => load(entry, args[1]?.pages)),
+		fetch: (factory, ...args) => Effect.flatMap(buildFor(factory, args[0]), (entry) => load(entry, args[1]?.pages, true)),
 		getData: (factory, ...args) => Effect.sync(() => {
 			const options = optionsFor(factory, args[0]);
 			const entry = state.entries.get(hashKey(options.queryKey));

package/dist/entry.d.mts

@@ -6,7 +6,7 @@ import { Pending, Thenable } from "./thenable.mjs";
 import { FetchRequest, Query, State, SubscribeOptions } from "./query.mjs";
 import { Cause, Clock, Context, Deferred, Effect, Scope, Stream } from "effect";
 declare namespace entry_d_exports {
-  export { CacheState, CancelledError, Entry, TypeId, changes, emit, entryOf, fetch, hasNextPageUnsafe, hasPreviousPageUnsafe, invalidate, isObserved, isQuery, isStaleUnsafe, make, metaOf, now, onPlatformEvent, provide, readUnsafe, remove, reset, resume, revalidate, setData, setOptions, start, subscribeUnsafe };
+  export { CacheState, CancelledError, Entry, TypeId, changes, emit, entryOf, fetch, hasNextPageUnsafe, hasPreviousPageUnsafe, invalidate, isObserved, isQuery, isStaleUnsafe, make, metaOf, needsRefetch, now, onPlatformEvent, provide, readUnsafe, remove, reset, resume, revalidate, setData, setOptions, start, subscribeUnsafe };
 }
 export declare const TypeId = "~@raf-query/core/Query";
 declare const CancelledError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => Cause.YieldableError & {
@@ -112,10 +112,12 @@ export declare function readUnsafe(entry: Entry): Thenable<unknown>;
 /** Start a request unless one is in flight, without waiting for it. */
 export declare function start(entry: Entry): void;
 /**
- * Background refetch of cached data that was asked for again. A server cache
- * renders once, so a refetch there could only duplicate a request whose
+ * Whether cached data that was asked for again should be refetched. A server
+ * cache renders once, so a refetch there could only duplicate a request whose
  * result is never shown; it refetches only what `invalidate` marked.
  */
+export declare function needsRefetch(entry: Entry): boolean;
+/** Background refetch of cached data that was asked for again. */
 export declare function revalidate(entry: Entry): void;
 export declare function fetch(entry: Entry, request?: FetchRequest): Effect.Effect<unknown, unknown>;
 export declare function invalidate(entry: Entry): Effect.Effect<void>;

package/dist/entry.mjs

@@ -189,14 +189,17 @@ function start(entry) {
 	begin(entry, {});
 }
 /**
-* Background refetch of cached data that was asked for again. A server cache
-* renders once, so a refetch there could only duplicate a request whose
+* Whether cached data that was asked for again should be refetched. A server
+* cache renders once, so a refetch there could only duplicate a request whose
 * result is never shown; it refetches only what `invalidate` marked.
 */
+function needsRefetch(entry) {
+	return entry.cache.isServer ? entry.state.isInvalidated : isStaleUnsafe(entry);
+}
+/** Background refetch of cached data that was asked for again. */
 function revalidate(entry) {
 	const state = entry.state;
-	if (!state.hasData || state.isFetching) return;
-	if (entry.cache.isServer ? state.isInvalidated : isStaleUnsafe(entry)) start(entry);
+	if (state.hasData && !state.isFetching && needsRefetch(entry)) start(entry);
 }
 function fetch(entry, request = {}) {
 	return Effect.suspend(() => {
@@ -496,4 +499,4 @@ function scheduleStale(entry) {
 	entry.tasks.fork("stale", Effect.sleep(Math.max(remaining, 0) + 1).pipe(Effect.andThen(Effect.sync(() => set(entry, {})))));
 }
 //#endregion
-export { CancelledError, TypeId, changes, emit, entryOf, fetch, hasNextPageUnsafe, hasPreviousPageUnsafe, invalidate, isObserved, isQuery, isStaleUnsafe, make, metaOf, now, onPlatformEvent, provide, readUnsafe, remove, reset, resume, revalidate, setData, setOptions, start, subscribeUnsafe };
+export { CancelledError, TypeId, changes, emit, entryOf, fetch, hasNextPageUnsafe, hasPreviousPageUnsafe, invalidate, isObserved, isQuery, isStaleUnsafe, make, metaOf, needsRefetch, now, onPlatformEvent, provide, readUnsafe, remove, reset, resume, revalidate, setData, setOptions, start, subscribeUnsafe };

package/package.json

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