@raf-query/core 0.3.0 → 0.4.0

package/CHANGELOG.md

@@ -1,14 +1,28 @@
 # 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))
+
 ## [0.3.0](https://github.com/KATT/raf-query/compare/0.2.8...0.3.0) (2026-10-13)
 
 ### ⚠ BREAKING CHANGES
 
-* RSC apps hydrate only through HydrationBoundary; QueryProvider moves to /rsc ([#61](https://github.com/KATT/raf-query/issues/61))
+- RSC apps hydrate only through HydrationBoundary; QueryProvider moves to /rsc ([#61](https://github.com/KATT/raf-query/issues/61))
 
 ### Features
 
-* RSC apps hydrate only through HydrationBoundary; QueryProvider moves to /rsc ([#61](https://github.com/KATT/raf-query/issues/61)) ([772de79](https://github.com/KATT/raf-query/commit/772de796adfdf267a9184fd75624ff30ae53f4fc)), references [#59](https://github.com/KATT/raf-query/issues/59) [#59](https://github.com/KATT/raf-query/issues/59) [#59](https://github.com/KATT/raf-query/issues/59) [#59](https://github.com/KATT/raf-query/issues/59)
+- RSC apps hydrate only through HydrationBoundary; QueryProvider moves to /rsc ([#61](https://github.com/KATT/raf-query/issues/61)) ([772de79](https://github.com/KATT/raf-query/commit/772de796adfdf267a9184fd75624ff30ae53f4fc)), references [#59](https://github.com/KATT/raf-query/issues/59) [#59](https://github.com/KATT/raf-query/issues/59) [#59](https://github.com/KATT/raf-query/issues/59) [#59](https://github.com/KATT/raf-query/issues/59)
 
 ## [0.2.8](https://github.com/KATT/raf-query/compare/0.2.7...0.2.8) (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 in a server component, or building another input             |
+| 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
@@ -139,6 +149,13 @@ export const Route = createFileRoute("/posts/$slug")({
 });
 ```
 
+`prefetch` and `ensure` start the request at the same moment, so neither is faster. They differ in what the user sees while it's in flight:
+
+- **`prefetch`: granular skeletons.** The navigation commits right away. Each part of the page that reads a query still loading suspends to its nearest Suspense boundary and fills in when its data streams in.
+- **`ensure`: a blocked navigation.** The previous page stays on screen until the data is in. In TanStack Router, a route with a `pendingComponent` shows it once `pendingMs` (1 second by default) has passed, which makes a full-page skeleton.
+
+Choose per query. `ensure` what the page can't lay out without, where a skeleton would only flash or shift (the post itself), and `prefetch` the rest (comments, sidebars, counts). Start every query before awaiting any of them, as the `prefetch` before the `await` above does, so a blocking query never delays the others.
+
 Await independent blocking queries together with `allKeyed`, which ships with raf-query. It's a ponyfill of the TC39 `Promise.allKeyed` proposal: a record of promises in, a promise of the same record out, rejecting on the first failure.
 
 ```ts
@@ -150,17 +167,78 @@ return await allKeyed({
 });
 ```
 
-Dependent inputs use `fetch`:
+### Avoid dependent queries
+
+A query whose input comes from another query's result can't start until that one has finished. That's a waterfall: one extra round trip per level, on every navigation. Fix it where the data is shaped, so every query a route needs starts from what the URL already holds:
+
+- **Put the input in the route.** If the page is about an organization, its id belongs in the path (`/orgs/$orgId`), not in a lookup on the current user.
+- **Have the backend resolve it.** The server already knows the session and the relations, so an endpoint can return the child with its parent, or be keyed by what the client has (`GET /me/org` instead of `GET /me` then `GET /orgs/:id`).
+
+<details>
+<summary>Example: the current user's organization</summary>
+
+A settings page needs the user and their organization, and the organization's id is a field of the user:
+
+```ts
+export const Route = createFileRoute("/settings")({
+	loader: async (args) => {
+		const qc = args.context.queryClient;
+		const user = await qc.fetch(currentUserQuery);
+		return {
+			user: qc.prefetch(currentUserQuery),
+			org: qc.prefetch(orgQuery, { orgId: user.orgId }),
+		};
+	},
+});
+```
+
+With a 150 ms round trip, the organization can't arrive before 300 ms, and the navigation is blocked for the first 150 even though nothing on the page needed the user that early. Each query keyed by the organization (members, billing) would add another 150.
+
+Fix it in the backend: the server can find the session's organization itself, so give it an endpoint and a query with no input.
+
+```ts
+export function currentOrgQuery() {
+	return queryOptions({
+		queryKey: ["org", "current"],
+		queryFn: () => getCurrentOrg(),
+	});
+}
+
+export const Route = createFileRoute("/settings")({
+	loader: (args) => {
+		const qc = args.context.queryClient;
+		return {
+			user: qc.prefetch(currentUserQuery),
+			org: qc.prefetch(currentOrgQuery),
+		};
+	},
+});
+```
+
+Or fix it in the routes: links into the page come from places that already know the organization (the org switcher, a list of orgs), so they can put its id in the URL.
 
 ```ts
-const user = await qc.fetch(currentUserQuery);
-return { org: qc.prefetch(orgQuery, { orgId: user.orgId }) };
+export const Route = createFileRoute("/orgs/$orgId/settings")({
+	loader: (args) => {
+		const qc = args.context.queryClient;
+		return {
+			user: qc.prefetch(currentUserQuery),
+			org: qc.prefetch(orgQuery, { orgId: args.params.orgId }),
+		};
+	},
+});
 ```
 
+Either way, both requests start together, and the page is ready after one round trip instead of two. Nothing waits, so each query can be a `prefetch` or an `ensure` purely for the loading experience you want.
+
+</details>
+
+When the data really can't be reshaped (a third-party API you don't control), the loader can `await qc.fetch(...)` the parent and build the input from its data, or a component can start the child with [`useWaterfall`](#render-time-inputs-usewaterfall). Both pay the extra round trip; the loader blocks the navigation on it, the component lets the rest of the page render first.
+
 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`.
@@ -241,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.0",
+  "version": "0.4.0",
   "description": "Framework-agnostic core of raf-query, a render-as-you-fetch query library",
   "keywords": [
     "query",