@raf-query/react 0.1.0 → 0.1.2

package/CHANGELOG.md

@@ -1,19 +1,31 @@
 # 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))
+
 ## [0.1.0](https://github.com/KATT/raf-query/compare/0.0.19...0.1.0) (2026-10-12)
 
 ### ⚠ BREAKING CHANGES
 
-* Effect-native engine; core exposes only Effect APIs ([#23](https://github.com/KATT/raf-query/issues/23))
-* **core:** make QueryObserver an Effect-style data type ([#29](https://github.com/KATT/raf-query/issues/29))
+- Effect-native engine; core exposes only Effect APIs ([#23](https://github.com/KATT/raf-query/issues/23))
+- **core:** make QueryObserver an Effect-style data type ([#29](https://github.com/KATT/raf-query/issues/29))
 
-* **core:** make QueryObserver an Effect-style data type ([#29](https://github.com/KATT/raf-query/issues/29)) ([50fbb45](https://github.com/KATT/raf-query/commit/50fbb45bf3edcaa83673e2177894a76bdf76560b))
-* Effect-native engine; core exposes only Effect APIs ([#23](https://github.com/KATT/raf-query/issues/23)) ([8e0bb09](https://github.com/KATT/raf-query/commit/8e0bb09a63d644ede053f443406a521ff2613a6f))
+- **core:** make QueryObserver an Effect-style data type ([#29](https://github.com/KATT/raf-query/issues/29)) ([50fbb45](https://github.com/KATT/raf-query/commit/50fbb45bf3edcaa83673e2177894a76bdf76560b))
+- Effect-native engine; core exposes only Effect APIs ([#23](https://github.com/KATT/raf-query/issues/23)) ([8e0bb09](https://github.com/KATT/raf-query/commit/8e0bb09a63d644ede053f443406a521ff2613a6f))
 
 ### Features
 
-* **core:** stream SSR dehydration as Effect APIs; integrations become thin edges ([#30](https://github.com/KATT/raf-query/issues/30)) ([6b2b570](https://github.com/KATT/raf-query/commit/6b2b5703f5463c0f3805c233cf4ead90df9efb76)), references [#29](https://github.com/KATT/raf-query/issues/29)
-* typed services for Effect queries; QueryClient layer and dispose() ([#31](https://github.com/KATT/raf-query/issues/31)) ([6aeaa3d](https://github.com/KATT/raf-query/commit/6aeaa3d356f6483654729620ac26762508eb8fd8))
+- **core:** stream SSR dehydration as Effect APIs; integrations become thin edges ([#30](https://github.com/KATT/raf-query/issues/30)) ([6b2b570](https://github.com/KATT/raf-query/commit/6b2b5703f5463c0f3805c233cf4ead90df9efb76)), references [#29](https://github.com/KATT/raf-query/issues/29)
+- typed services for Effect queries; QueryClient layer and dispose() ([#31](https://github.com/KATT/raf-query/issues/31)) ([6aeaa3d](https://github.com/KATT/raf-query/commit/6aeaa3d356f6483654729620ac26762508eb8fd8))
 
 ## [0.0.19](https://github.com/KATT/raf-query/compare/0.0.18...0.0.19) (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:
@@ -358,12 +368,22 @@ function EditTitle(props: { post: Post }) {
 
 `updatePost` is a server function (or a Next.js server action). `await qc.invalidate(...)` resolves once every query currently being read has refetched, so the action's pending state lasts until the fresh data is on screen. For an error message, wrap the action in `useActionState` and return the caught error.
 
-| Call                                  | Effect                                                                  |
-| ------------------------------------- | ----------------------------------------------------------------------- |
-| `qc.invalidate(factory, input)`       | Mark one query stale and refetch it if it is being read                 |
-| `qc.invalidate({ queryKey, exact? })` | Same, for every query whose key starts with `queryKey` (unless `exact`) |
-| `qc.setData(factory, input, updater)` | Write data directly                                                     |
-| `qc.getData(factory, input)`          | Read cached data, or `undefined`                                        |
+| Call                                  | Effect                                                  |
+| ------------------------------------- | ------------------------------------------------------- |
+| `qc.invalidate(factory, input)`       | Mark one query stale and refetch it if it is being read |
+| `qc.invalidate(filter)`               | Same, for every query the [filter](#filters) selects    |
+| `qc.setData(factory, input, updater)` | Write data directly                                     |
+| `qc.getData(factory, input)`          | Read cached data, or `undefined`                        |
+
+### Filters
+
+`invalidate`, `reset` and `remove` also take a filter, `{ queryKey?, exact?, predicate? }`. `queryKey` selects every query whose key starts with it, or only that key with `exact: true`; object segments match partially, so `{ queryKey: ["issues", { projectId: 3 }] }` selects every issue list in project 3. `predicate` gets each remaining `Query` and keeps the ones it returns `true` for: read its `key` and `handle.input`, or use the `Query` functions (`Query.getUnsafe(query)` for its state, `Query.observerCountUnsafe(query)`, `Query.isStaleUnsafe(query)`). Without `queryKey` every key matches, so `{}` selects the whole cache.
+
+```ts
+qc.remove({ predicate: (query) => Query.observerCountUnsafe(query) === 0 }); // everything not being read
+```
+
+`handle.input` is the input of the latest factory call for that entry. An entry that was only hydrated, and not yet read or started on this client, has `undefined` input, so match on `key` to include those.
 
 Data can be `undefined` when the `queryFn`'s type allows it (`Promise<User | undefined>`); it's cached and reused like any other value, unlike in TanStack Query, where an `undefined` result is an error. So `getData` and an updater's `previous` return `undefined` both with no data and with `undefined` data; `Query.getUnsafe(qc.getQuery(factory, input)).hasData` tells them apart.
 
@@ -465,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`.
@@ -598,10 +618,11 @@ Both render nothing on the server, since the server's cache isn't the browser's.
 | `new QueryClient(config?)`                  | `config.defaults` (query options below), `config.onError`, `config.isServer`, `config.layer` ([services](#services))    |
 | `prefetch`, `ensure`, `fetch`               | [Start queries](#starting-queries)                                                                                      |
 | `invalidate`, `setData`, `getData`          | [Write and read the cache](#mutations)                                                                                  |
-| `reset(factory, input)` / `reset(filter)`   | Drop data and errors; read queries suspend and refetch. Resolves when they settle                                       |
-| `remove(factory, input)` / `remove(filter)` | Remove entries and abort their requests                                                                                 |
+| `reset(factory, input)` / `reset(filter)`   | Drop data and errors; read queries suspend and refetch. Resolves when they settle. [Filters](#filters)                  |
+| `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                                                      |
@@ -653,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/client.d.mts

@@ -46,7 +46,7 @@ export declare class QueryClient<TServices = never> {
   /**
    * Mark queries stale and refetch the ones being read. Resolves once those
    * refetches settle, so an action stays pending until fresh data is on
-   * screen. Takes a factory and its input, or a {@link QueryFilter}.
+   * screen. Takes a factory and its input, or a {@link QueryCache.Filter}.
    */
   invalidate<TFactory extends QueryFactory<TServices>>(...target: QueryCache.Target<TFactory>): Promise<void>;
   /**
@@ -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

@@ -66,7 +66,7 @@ var QueryClient = class {
 	/**
 	* Mark queries stale and refetch the ones being read. Resolves once those
 	* refetches settle, so an action stays pending until fresh data is on
-	* screen. Takes a factory and its input, or a {@link QueryFilter}.
+	* screen. Takes a factory and its input, or a {@link QueryCache.Filter}.
 	*/
 	invalidate(...target) {
 		return Effect.runPromise(this.effect.invalidate(...target));
@@ -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/devtools-panel.mjs

@@ -592,7 +592,7 @@ function Panel(props) {
 							}, order))
 						}),
 						/* @__PURE__ */ jsx("button", {
-							onClick: () => void client.invalidate({ queryKey: [] }),
+							onClick: () => void client.invalidate({}),
 							style: {
 								...control,
 								cursor: "pointer"

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.0",
+  "version": "0.1.2",
   "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.0",
+    "@raf-query/core": "0.1.2",
     "effect": "^4.0.1"
   },
   "peerDependencies": {