@raf-query/core 0.3.1 → 0.4.0

package/CHANGELOG.md

@@ -1,8 +1,18 @@
 # Changelog
 
+## [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

@@ -120,11 +120,21 @@ declare module "@raf-query/react" {
 
 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<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                       | Use for                                                                |
+| --------------------------------- | ----------------------------- | ---------------------------------------------------------------------- |
+| `qc.prefetch(factory, input)`     | `QueryHandle`                 | Data the route can render without; it streams in                       |
+| `await qc.ensure(factory, input)` | `Promise<EnsuredQueryHandle>` | Data the route must not render without; `useQuery` returns it directly |
+| `await qc.fetch(factory, input)`  | `Promise<Data>`               | Rendering data in a server component                                   |
+
+They differ in what they wait for:
+
+| Verb       | Cache miss            | Stale data                                    | Fresh data       | TanStack Query                                 |
+| ---------- | --------------------- | --------------------------------------------- | ---------------- | ---------------------------------------------- |
+| `prefetch` | Starts the request    | Refetches in the background                   | Reused           | `prefetchQuery`, not awaited                   |
+| `ensure`   | Waits for the request | Resolves at once, refetches in the background | Resolves at once | `ensureQueryData({ revalidateIfStale: true })` |
+| `fetch`    | Waits for the request | Waits for the refetch                         | Resolves at once | `fetchQuery`                                   |
+
+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 +237,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 +319,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.
 

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