@raf-query/core 0.1.1 → 0.1.3

package/CHANGELOG.md

@@ -1,10 +1,22 @@
 # Changelog
 
+## [0.1.3](https://github.com/KATT/raf-query/compare/0.1.2...0.1.3) (2026-10-12)
+
+### Features
+
+* **core:** cancel requests nobody reads anymore ([#27](https://github.com/KATT/raf-query/issues/27)) ([c3c1e4b](https://github.com/KATT/raf-query/commit/c3c1e4bb9250164b6df17d7d4b7bd4043f908961))
+
+## [0.1.2](https://github.com/KATT/raf-query/compare/0.1.1...0.1.2) (2026-10-12)
+
+### Features
+
+- add isFetching(filter?) and useIsFetching(filter?) ([#25](https://github.com/KATT/raf-query/issues/25)) ([70c3b98](https://github.com/KATT/raf-query/commit/70c3b981027f717b1d619d5a2b23822f685c032a))
+
 ## [0.1.1](https://github.com/KATT/raf-query/compare/0.1.0...0.1.1) (2026-10-12)
 
 ### Features
 
-* **core:** add predicate to QueryFilter ([#24](https://github.com/KATT/raf-query/issues/24)) ([c0b9c18](https://github.com/KATT/raf-query/commit/c0b9c1829cb3b6446f765b151e520f0195af5276))
+- **core:** add predicate to QueryFilter ([#24](https://github.com/KATT/raf-query/issues/24)) ([c0b9c18](https://github.com/KATT/raf-query/commit/c0b9c1829cb3b6446f765b151e520f0195af5276))
 
 ## [0.1.0](https://github.com/KATT/raf-query/compare/0.0.19...0.1.0) (2026-10-12)
 

package/README.md

@@ -196,6 +196,16 @@ When the cache updates — refetch, invalidation, `setData` — the hook returns
 
 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`.
 
+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.
+
+```tsx
+// Rendered once, in the root layout.
+function GlobalProgress() {
+	const fetching = useIsFetching();
+	return fetching > 0 ? <ProgressBar /> : null;
+}
+```
+
 ### Paged queries
 
 With an `infiniteQueryOptions` factory, `useQuery` returns the same tuple. The promise resolves to `{ pages, pageParams }`, and the controls add paging:
@@ -475,7 +485,7 @@ raf-query's cache is written in [Effect](https://effect.website): `QueryClient`
 - A `queryFn` can return an `Effect`. Cancelling the request interrupts it.
 - An Effect `queryFn`'s error type is the query's: `qc.effect.fetch(issueQuery, input)` fails with `IssueNotFound | Query.CancelledError`. `ErrorOf<TFactory>` names it; it's `unknown` for promises. A `queryFn` that throws instead of returning is a defect, and isn't retried.
 - `retry` accepts a `Schedule` as well as a count or predicate.
-- `qc.effect` has every verb as an Effect: `prefetch`, `ensure`, `fetch`, `invalidate`, `reset`, `remove`, `setData`, `getData` (an `Option`), `dehydrate`, `hydrate`. `watch` is a `Stream` of an entry's state, and `events` a `Stream` of cache events.
+- `qc.effect` has every verb as an Effect: `prefetch`, `ensure`, `fetch`, `invalidate`, `reset`, `remove`, `setData`, `getData` (an `Option`), `isFetching` (a count), `dehydrate`, `hydrate`. `watch` is a `Stream` of an entry's state, and `events` a `Stream` of cache events.
 - SSR streaming is Effect too, and the integrations are thin wrappers over it. `dehydrateStream(options)` (scoped) returns the cache's `initial` state and a `Stream` of `updates`: entries that start or settle later, each sent once, batched per microtask. The stream ends when the scope closes. `hydrateStream(stream)` hydrates each state as it arrives. `Stream.toReadableStream` / `Stream.fromReadableStream` carry it over a web stream. The `sent` option (a `Set` of hashes) makes separate `dehydrate` calls of one request skip entries already sent.
 - Entries are a data type with module functions, as in Effect's own modules: `Query.fetch(query)`, `Query.refetch(query)`, `Query.invalidate(query)`, `Query.changes(query)`, and `Query.getUnsafe(query)` / `Query.subscribeUnsafe(query, listener)` for synchronous reads.
 - `QueryObserver` is a data type too: one reader's view of a query, as `useQuery` sees it (the controls and the promise, with `whilePending`, `refetchInterval` and the focus / reconnect options). `QueryObserver.make(query, options)` creates one, and `QueryObserver.changes(observer)` streams its results; while it runs, the query counts as read and polls on `refetchInterval`.
@@ -612,6 +622,7 @@ Both render nothing on the server, since the server's cache isn't the browser's.
 | `remove(factory, input)` / `remove(filter)` | Remove entries and abort their requests. [Filters](#filters)                                                            |
 | `effect`                                    | The [Effect](#effect) `QueryCache` behind the client                                                                    |
 | `subscribe(listener)`                       | Cache events: `added`, `updated`, `observers` (a reader subscribed or left), `removed`, and `failed` (with the `error`) |
+| `isFetching(filter?)`                       | How many entries have a request in flight, optionally only those matching `{ queryKey, exact? }`                        |
 | `getAll()`, `getQuery(factory, input?)`     | Cache entries, for devtools and integrations                                                                            |
 | `clear()`                                   | Drop every entry and abort in-flight requests                                                                           |
 | `mount()`                                   | Start window-focus and reconnect refetching. The providers call it                                                      |
@@ -633,6 +644,8 @@ Query options, accepted by `queryOptions`, `infiniteQueryOptions` and `config.de
 
 In the browser, retries pause while `navigator.onLine` is `false`: after the retry delay, the next attempt waits for the window's `online` event. The request stays fetching meanwhile, and cancelling it (`remove`, `clear`, a restart) stops the wait. The first attempt runs regardless.
 
+When the last reader of a query unsubscribes during a background refetch, a `queryFn` that read its `signal` (or returned an Effect) is aborted: the entry keeps its data and goes back to how it was before the request, and `fetch` callers waiting on it get the cached data. Other requests, including every first load (a render may be suspended on it), finish so their result is cached, but don't retry unless a reader comes back. Requests nothing has subscribed to yet, like a loader's `prefetch`, keep running.
+
 `@raf-query/core`:
 
 | Export                                                       | Use                                                                        |
@@ -663,6 +676,7 @@ In the browser, retries pause while `navigator.onLine` is `false`: after the ret
 | `useQueryClient()`                             | Read the client                                                                                                 |
 | `useQuery(factory, handle, options?)`          | `[Thenable<Data>, controls]`; for paged factories `Data` is `{ pages, pageParams }` and controls include paging |
 | `useWaterfall(factory, input)`                 | Start a query during render and return its handle                                                               |
+| `useIsFetching(filter?)`                       | How many queries have a request in flight, re-rendering when it changes; for global loading indicators          |
 
 ## Development
 

package/dist/cache.d.mts

@@ -109,6 +109,13 @@ export interface QueryCache {
    * screen.
    */
   invalidate<TFactory extends QueryFactory>(...target: Target<TFactory>): Effect.Effect<void>;
+  /**
+   * How many entries have a request in flight: all of them, or those
+   * matching `filter`. For global loading indicators.
+   */
+  isFetching(filter?: Filter): Effect.Effect<number>;
+  /** `isFetching`, synchronously, for renders. */
+  isFetchingUnsafe(filter?: Filter): number;
   readonly isServer: boolean;
   /**
    * Refetch read, stale queries on window focus and reconnect while the

package/dist/cache.mjs

@@ -11,8 +11,9 @@ import { Clock, Context, Effect, Layer, Option, Predicate, RcRef, Stream } from
 /**
 * The query cache, as an Effect service. `make` builds one in the current
 * scope; closing the scope interrupts every request and timer it started.
-* Everything that waits, or changes the cache, is an Effect; `getQueryUnsafe`
-* and `subscribeUnsafe` are for renders and external stores.
+* Everything that waits, or changes the cache, is an Effect; `getQueryUnsafe`,
+* `isFetchingUnsafe` and `subscribeUnsafe` are for renders and external
+* stores.
 *
 * Requests run with the services the cache was built with, under those of
 * the latest verb that called for the entry. So the verbs that can start a
@@ -135,6 +136,7 @@ const make = Effect.fnUntraced(function* (config = {}) {
 		};
 	};
 	const getQueryUnsafe = (factory, ...args) => typed(build(factory, args[0]));
+	const isFetchingUnsafe = (filter) => (filter ? match([filter]) : [...state.entries.values()]).filter((entry) => entry.state.isFetching).length;
 	return {
 		all: Effect.sync(() => [...state.entries.values()]),
 		clear: Effect.sync(() => {
@@ -158,6 +160,8 @@ const make = Effect.fnUntraced(function* (config = {}) {
 		hydrate: (dehydrated, options = {}) => Effect.sync(() => hydrateEntries(entryFor, dehydrated, options)),
 		hydrateStream: (states, options = {}) => Stream.runForEach(states, (dehydrated) => Effect.sync(() => hydrateEntries(entryFor, dehydrated, options))),
 		invalidate: (...target) => Effect.suspend(() => settleAll(match(target).map(invalidate))),
+		isFetching: (filter) => Effect.sync(() => isFetchingUnsafe(filter)),
+		isFetchingUnsafe,
 		isServer: state.isServer,
 		mount: state.isServer ? Effect.void : Effect.asVoid(RcRef.get(subscription)),
 		prefetch: (factory, ...args) => Effect.map(buildFor(factory, args[0]), (entry) => {

package/dist/entry.d.mts

@@ -54,6 +54,8 @@ export interface Entry extends Query {
   readonly commands: Commands;
   /** A failed first load was shown; the next read retries it. */
   errorShown: boolean;
+  /** `failureCount` before the request in flight, restored if it's cancelled. */
+  failureCountBefore: number;
   handle: QueryHandle;
   /** Awaited by every caller of the request in flight; outlives restarts. */
   inFlight: Deferred.Deferred<unknown, unknown> | undefined;
@@ -61,6 +63,8 @@ export interface Entry extends Query {
   options: AnyQueryOptions | undefined;
   /** The first load's promise, until it settles. */
   pending: Pending<unknown> | undefined;
+  /** The last reader left during the request in flight: it retries no more. */
+  retriesStopped: boolean;
   /** Open while the entry is cached; owns its fibers. */
   readonly scope: Scope.Closeable;
   /**
@@ -68,6 +72,11 @@ export interface Entry extends Query {
    * latest verb that called for this entry ({@link provide}).
    */
   services: Context.Context<never>;
+  /**
+   * The request in flight read its `signal`, or returned an Effect, so
+   * interrupting it cancels its work (TanStack's `abortSignalConsumed`).
+   */
+  signalRead: boolean;
   state: State<unknown>;
   readonly tasks: Tasks;
 }

package/dist/entry.mjs

@@ -7,7 +7,7 @@ import { fromQueryFn, requestServices, runRequest } from "./request.mjs";
 import { retrySchedule } from "./retry.mjs";
 import { replaceEqualDeep } from "./share.mjs";
 import { fulfilled, pending } from "./thenable.mjs";
-import { Cause, Data, Deferred, Effect, Exit, FiberMap, Pipeable, Predicate, Scope } from "effect";
+import { Cause, Data, Deferred, Effect, Exit, FiberMap, Pipeable, Predicate, Schedule, Scope } from "effect";
 //#region src/entry.ts
 const TypeId = "~@raf-query/core/Query";
 /**
@@ -55,6 +55,7 @@ function make(cache, key, hash) {
 	const entry = Object.assign(Object.create(Proto), {
 		cache,
 		errorShown: false,
+		failureCountBefore: 0,
 		handle: {
 			input: void 0,
 			key
@@ -65,8 +66,10 @@ function make(cache, key, hash) {
 		listeners: /* @__PURE__ */ new Map(),
 		options: void 0,
 		pending: first,
+		retriesStopped: false,
 		scope,
 		services: cache.services,
+		signalRead: false,
 		state: {
 			data: void 0,
 			error: null,
@@ -121,6 +124,7 @@ function hasPreviousPageUnsafe(entry) {
 }
 function subscribeUnsafe(entry, listener, options = defaultSubscribeOptions) {
 	entry.listeners.set(listener, options);
+	entry.retriesStopped = false;
 	entry.tasks.cancel("gc");
 	scheduleStale(entry);
 	emit(entry.cache, {
@@ -132,6 +136,8 @@ function subscribeUnsafe(entry, listener, options = defaultSubscribeOptions) {
 		if (entry.listeners.size === 0) {
 			entry.tasks.cancel("stale");
 			scheduleGc(entry);
+			const inFlight = entry.inFlight;
+			if (inFlight) scheduleNotify(() => unobserved(entry, inFlight));
 		}
 		emit(entry.cache, {
 			query: entry,
@@ -273,8 +279,11 @@ function set(entry, patch) {
 }
 /** Run `request` as the entry's request fiber, settling into its awaiter. */
 function startRequest(entry, request, direction) {
+	if (!entry.inFlight) entry.failureCountBefore = entry.state.failureCount;
 	const awaiter = entry.inFlight ?? Deferred.makeUnsafe();
 	entry.inFlight = awaiter;
+	entry.retriesStopped = false;
+	entry.signalRead = false;
 	entry.tasks.cancel("gc");
 	if (!entry.state.hasData && entry.state.status === "error") {
 		entry.pending = pending();
@@ -312,6 +321,29 @@ function settle(entry, awaiter, exit) {
 	}
 	scheduleGc(entry);
 }
+/**
+* The last reader left while `awaiter`'s request was in flight. A refetch
+* whose work an interrupt cancels (`signalRead`) is interrupted, and the
+* entry goes back to its state before the request; its awaiters get the
+* cached data. Any other request finishes, so its result is cached, but
+* runs no more retries.
+*/
+function unobserved(entry, awaiter) {
+	if (isObserved(entry) || entry.inFlight !== awaiter) return;
+	if (!entry.signalRead || !entry.state.hasData) {
+		entry.retriesStopped = true;
+		return;
+	}
+	entry.inFlight = void 0;
+	entry.tasks.cancel("request");
+	set(entry, {
+		failureCount: entry.failureCountBefore,
+		fetchDirection: void 0,
+		isFetching: false
+	});
+	Deferred.doneUnsafe(awaiter, Exit.succeed(entry.state.data));
+	scheduleGc(entry);
+}
 function succeed(entry, next, updatedAt) {
 	const previous = entry.state;
 	const data = previous.hasData && behavior(entry, "structuralSharing") !== false ? replaceEqualDeep(previous.data, next) : next;
@@ -365,24 +397,37 @@ function markErrorShown(entry) {
 }
 function requestEffect(entry, options, request) {
 	const queryKey = options.queryKey;
-	if (options.kind === "query") return attempt(entry, (signal) => options.queryFn({
+	if (options.kind === "query") return attempt(entry, (readSignal) => options.queryFn({
 		queryKey,
-		signal
+		get signal() {
+			return readSignal();
+		}
 	}));
 	const current = isInfiniteData(entry.state.data) ? entry.state.data : void 0;
-	return fetchPages(options, current, request, (pageParam, direction) => attempt(entry, (signal) => options.queryFn({
+	return fetchPages(options, current, request, (pageParam, direction) => attempt(entry, (readSignal) => options.queryFn({
 		direction,
 		pageParam,
 		queryKey,
-		signal
+		get signal() {
+			return readSignal();
+		}
 	})));
 }
 /**
 * One `queryFn` call, retried per the query's policy. Every failure counts.
-* Its services are erased with its data type; `runRequest` provides them.
+* `call` reads the signal through `readSignal`, which marks the entry's
+* `signalRead`. Its services are erased with its data type; `runRequest`
+* provides them.
 */
 function attempt(entry, call) {
-	const once = fromQueryFn(call).pipe(Effect.tapError(() => Effect.sync(() => set(entry, { failureCount: entry.state.failureCount + 1 }))));
+	const once = fromQueryFn((signal) => {
+		const result = call(() => {
+			entry.signalRead = true;
+			return signal;
+		});
+		if (Effect.isEffect(result)) entry.signalRead = true;
+		return result;
+	}).pipe(Effect.tapError(() => Effect.sync(() => set(entry, { failureCount: entry.state.failureCount + 1 }))));
 	const schedule = retrySchedule({
 		retry: behavior(entry, "retry"),
 		retryDelay: behavior(entry, "retryDelay")
@@ -391,12 +436,18 @@ function attempt(entry, call) {
 	const online = entry.cache.isServer ? Effect.void : whenOnline;
 	return Effect.suspend(() => {
 		let retrying = false;
+		let lastError;
+		const unlessStopped = (next) => Effect.suspend(() => entry.retriesStopped ? Effect.fail(lastError) : next);
 		const gated = Effect.suspend(() => {
-			const wait = retrying ? online : Effect.void;
-			retrying = true;
-			return Effect.andThen(wait, once);
-		});
-		return Effect.retry(gated, schedule);
+			if (!retrying) {
+				retrying = true;
+				return once;
+			}
+			return unlessStopped(Effect.andThen(online, unlessStopped(once)));
+		}).pipe(Effect.tapError((error) => Effect.sync(() => {
+			lastError = error;
+		})));
+		return Effect.retry(gated, Schedule.while(schedule, () => !entry.retriesStopped));
 	});
 }
 function scheduleGc(entry) {

package/package.json

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