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

@@ -69,6 +69,11 @@ export declare class QueryClient<TServices = never> {
   getData<TFactory extends QueryFactory<TServices>>(factory: TFactory, ...args: InputArgs<TFactory>): DataOf<TFactory> | undefined;
   /** Every entry, for devtools and integrations. */
   getAll(): ReadonlyArray<Query.Query>;
+  /**
+   * How many entries have a request in flight: all of them, or those
+   * matching `filter`. For global loading indicators.
+   */
+  isFetching(filter?: QueryCache.Filter): number;
   /** Listen to entries being added, updated, and removed. */
   subscribe(listener: (event: QueryCache.Event) => void): () => void;
   /** Drop every entry and abort in-flight requests. */

package/dist/client.mjs

@@ -101,6 +101,13 @@ var QueryClient = class {
 	getAll() {
 		return Effect.runSync(this.effect.all);
 	}
+	/**
+	* How many entries have a request in flight: all of them, or those
+	* matching `filter`. For global loading indicators.
+	*/
+	isFetching(filter) {
+		return this.effect.isFetchingUnsafe(filter);
+	}
 	/** Listen to entries being added, updated, and removed. */
 	subscribe(listener) {
 		return this.effect.subscribeUnsafe(listener);

package/dist/index.d.mts

@@ -1,7 +1,8 @@
 import { QueryClient, QueryClientConfig, dehydrate, hydrate } from "./client.mjs";
 import { Settled, allKeyed } from "./all-keyed.mjs";
 import { QueryClientProvider, useQueryClient } from "./provider.mjs";
+import { useIsFetching } from "./use-is-fetching.mjs";
 import { PagingControls, QueryControls, UseEnsuredQueryResult, UseQueryControls, UseQueryOptions, UseQueryResult, useQuery } from "./use-query.mjs";
 import { useWaterfall } from "./use-waterfall.mjs";
 export * from "@raf-query/core";
-export { type PagingControls, QueryClient, type QueryClientConfig, QueryClientProvider, type QueryControls, type Settled, type UseEnsuredQueryResult, type UseQueryControls, type UseQueryOptions, type UseQueryResult, allKeyed, dehydrate, hydrate, useQuery, useQueryClient, useWaterfall };
+export { type PagingControls, QueryClient, type QueryClientConfig, QueryClientProvider, type QueryControls, type Settled, type UseEnsuredQueryResult, type UseQueryControls, type UseQueryOptions, type UseQueryResult, allKeyed, dehydrate, hydrate, useIsFetching, useQuery, useQueryClient, useWaterfall };

package/dist/index.mjs

@@ -1,7 +1,8 @@
 import { allKeyed } from "./all-keyed.mjs";
 import { QueryClient, dehydrate, hydrate } from "./client.mjs";
 import { QueryClientProvider, useQueryClient } from "./provider.mjs";
+import { useIsFetching } from "./use-is-fetching.mjs";
 import { useQuery } from "./use-query.mjs";
 import { useWaterfall } from "./use-waterfall.mjs";
 export * from "@raf-query/core";
-export { QueryClient, QueryClientProvider, allKeyed, dehydrate, hydrate, useQuery, useQueryClient, useWaterfall };
+export { QueryClient, QueryClientProvider, allKeyed, dehydrate, hydrate, useIsFetching, useQuery, useQueryClient, useWaterfall };

package/dist/use-is-fetching.d.mts

@@ -0,0 +1,15 @@
+import { QueryCache } from "@raf-query/core";
+//#region src/use-is-fetching.d.ts
+/**
+ * How many queries have a request in flight: all of them, or those matching
+ * `filter`. Re-renders when the count changes, for global loading
+ * indicators. It's `0` on the server and while hydrating, so the server's
+ * HTML and the browser's first render agree:
+ *
+ * ```tsx
+ * const fetching = useIsFetching();
+ * return fetching > 0 ? <ProgressBar /> : null;
+ * ```
+ */
+export declare function useIsFetching(filter?: QueryCache.Filter): number;
+//#endregion

package/dist/use-is-fetching.mjs

@@ -0,0 +1,35 @@
+"use client";
+import { useQueryClient } from "./provider.mjs";
+import { useCallback, useSyncExternalStore } from "react";
+//#region src/use-is-fetching.ts
+function subscribeDeferred(client, onStoreChange) {
+	let scheduled = false;
+	return client.subscribe(() => {
+		if (scheduled) return;
+		scheduled = true;
+		queueMicrotask(() => {
+			scheduled = false;
+			onStoreChange();
+		});
+	});
+}
+const none = () => 0;
+/**
+* How many queries have a request in flight: all of them, or those matching
+* `filter`. Re-renders when the count changes, for global loading
+* indicators. It's `0` on the server and while hydrating, so the server's
+* HTML and the browser's first render agree:
+*
+* ```tsx
+* const fetching = useIsFetching();
+* return fetching > 0 ? <ProgressBar /> : null;
+* ```
+*/
+function useIsFetching(filter) {
+	const client = useQueryClient();
+	const subscribe = useCallback((onStoreChange) => subscribeDeferred(client, onStoreChange), [client]);
+	const getSnapshot = () => client.isFetching(filter);
+	return useSyncExternalStore(subscribe, getSnapshot, none);
+}
+//#endregion
+export { useIsFetching };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@raf-query/react",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "React bindings for raf-query, a render-as-you-fetch query library",
   "keywords": [
     "query",
@@ -40,7 +40,7 @@
     "./tanstack-router": "./dist/tanstack-router.mjs"
   },
   "dependencies": {
-    "@raf-query/core": "0.1.1",
+    "@raf-query/core": "0.1.3",
     "effect": "^4.0.1"
   },
   "peerDependencies": {