@raf-query/core 0.1.1 → 0.1.2

package/CHANGELOG.md

@@ -1,10 +1,16 @@
 # Changelog
 
+## [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                                                      |
@@ -663,6 +674,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/package.json

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