@raf-query/core 0.0.6 → 0.0.7

package/CHANGELOG.md

@@ -1,8 +1,14 @@
 # Changelog
 
+## [0.0.7](https://github.com/KATT/raf-query/compare/0.0.6...0.0.7) (2026-10-12)
+
+### Features
+
+* **react:** add @raf-query/react/devtools ([#7](https://github.com/KATT/raf-query/issues/7)) ([e325d76](https://github.com/KATT/raf-query/commit/e325d76305e29f935228a2dbad6834b0309229e4))
+
 ## [0.0.6](https://github.com/KATT/raf-query/compare/0.0.5...0.0.6) (2026-10-12)
 
-* experimental @raf-query/tanstack-react-query on TanStack Query ([#8](https://github.com/KATT/raf-query/issues/8)) ([9d909c4](https://github.com/KATT/raf-query/commit/9d909c46ca030fd465d7af0fcd9591818356dd80))
+- experimental @raf-query/tanstack-react-query on TanStack Query ([#8](https://github.com/KATT/raf-query/issues/8)) ([9d909c4](https://github.com/KATT/raf-query/commit/9d909c46ca030fd465d7af0fcd9591818356dd80))
 
 ## [0.0.5](https://github.com/KATT/raf-query/compare/0.0.4...0.0.5) (2026-10-12)
 

package/README.md

@@ -17,13 +17,14 @@ Early. Both packages are on npm at `0.0.x`, and the API can still change between
 | `@raf-query/core`  | Framework-agnostic: `QueryClient`, cache, `queryOptions` / `infiniteQueryOptions`, handles, dehydrate / hydrate stream, `allKeyed` |
 | `@raf-query/react` | Hooks and provider. Re-exports everything from `@raf-query/core`, so apps install and import only this package                     |
 
-`@raf-query/react` subpath entries for framework integrations:
+`@raf-query/react` subpath entries for framework integrations and tooling:
 
 | Entry                              | Use                                                                    |
 | ---------------------------------- | ---------------------------------------------------------------------- |
 | `@raf-query/react/tanstack-router` | Streams the router's query cache to the client during SSR              |
 | `@raf-query/react/rsc`             | `HydrationBoundary` for passing server-component queries to the client |
 | `@raf-query/react/next`            | `QueryProvider` for Next.js App Router                                 |
+| `@raf-query/react/devtools`        | [Devtools](#devtools) panel for inspecting the cache in development    |
 
 ## Principles
 
@@ -470,21 +471,64 @@ const program = Effect.gen(function* () {
 
 `watch` counts as a reader while it runs, so invalidation and window focus refetch the entry.
 
+## Devtools
+
+`@raf-query/react/devtools` shows the browser's query cache as it changes. Render `QueryDevtools` anywhere under the provider:
+
+```tsx
+import { QueryDevtools } from "@raf-query/react/devtools";
+
+<QueryClientProvider client={queryClient}>
+	{props.children}
+	<QueryDevtools />
+</QueryClientProvider>;
+```
+
+In Next.js, put it inside `QueryProvider` in the root layout. It's a client component, so a server-component layout can render it.
+
+A button in the corner opens a panel docked to the edge of the viewport. The panel lists every entry with its observer count (mounted readers) and status:
+
+| Status     | Meaning                                    |
+| ---------- | ------------------------------------------ |
+| `fetching` | A request is in flight                     |
+| `error`    | The last request failed                    |
+| `stale`    | Read, and older than `staleTime`           |
+| `fresh`    | Read, and within `staleTime`               |
+| `inactive` | Nothing reads it; it's removed at `gcTime` |
+
+Select an entry to see its key, input, data, error, and last update, and to **Refetch**, **Invalidate**, **Reset** (drop its data, so readers suspend and refetch) or **Remove** it. The header filters entries by key, sorts them, and has **Invalidate all** and **Clear cache**. The panel keeps its open state and size in `localStorage`.
+
+`QueryDevtools` props, all optional:
+
+| Prop             | Values (default first)                                         |
+| ---------------- | -------------------------------------------------------------- |
+| `client`         | The nearest `QueryClientProvider`'s client, or another one     |
+| `initialIsOpen`  | `false`, `true`. Applies until the user opens or closes it     |
+| `buttonPosition` | `"bottom-right"`, `"bottom-left"`, `"top-right"`, `"top-left"` |
+| `position`       | `"bottom"`, `"top"`, `"left"`, `"right"`: the docked edge      |
+| `theme`          | `"system"`, `"dark"`, `"light"`                                |
+
+`QueryDevtoolsPanel` is the panel alone, to place in your own layout. It takes `client`, `theme`, `style`, and `onClose`, which adds a close button.
+
+Both render nothing on the server, since the server's cache isn't the browser's. They also render nothing when `process.env.NODE_ENV` is `"production"`, and bundlers drop the panel's code from production builds. To ship the panel in production, for example lazily behind a flag, import from `@raf-query/react/devtools/production`.
+
 ## API reference
 
 `QueryClient`:
 
-| Member                                  | Use                                                                             |
-| --------------------------------------- | ------------------------------------------------------------------------------- |
-| `new QueryClient(config?)`              | `config.defaults` (query options below), `config.onError`, `config.isServer`    |
-| `prefetch`, `ensure`, `fetch`           | [Start queries](#starting-queries)                                              |
-| `invalidate`, `setData`, `getData`      | [Write and read the cache](#mutations)                                          |
-| `effect`                                | [Effect versions](#effect) of `ensure`, `fetch`, `invalidate`, plus `watch`     |
-| `subscribe(listener)`                   | Cache events: `added`, `updated`, `removed`, and `failed` (with the `error`)    |
-| `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              |
-| `isServer`                              | Detected from `window`. Server clients don't retry, never gc, skip stale timers |
+| Member                                      | Use                                                                                                                     |
+| ------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
+| `new QueryClient(config?)`                  | `config.defaults` (query options below), `config.onError`, `config.isServer`                                            |
+| `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                                                                                 |
+| `effect`                                    | [Effect versions](#effect) of `ensure`, `fetch`, `invalidate`, plus `watch`                                             |
+| `subscribe(listener)`                       | Cache events: `added`, `updated`, `observers` (a reader subscribed or left), `removed`, and `failed` (with the `error`) |
+| `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                                                      |
+| `isServer`                                  | Detected from `window`. Server clients don't retry, never gc, skip stale timers                                         |
 
 Query options, accepted by `queryOptions`, `infiniteQueryOptions` and `config.defaults`:
 

package/dist/client.d.mts

@@ -17,7 +17,8 @@ export interface QueryClientConfig {
 /** Emitted by {@link QueryClient.subscribe} for every cache change. */
 export type CacheEvent = {
   readonly query: Query;
-  readonly type: "added" | "removed" | "updated";
+  /** `observers`: a reader subscribed or unsubscribed. */
+  readonly type: "added" | "observers" | "removed" | "updated";
 } | {
   /** A request failed (after retries), with this error. */
   readonly error: unknown;
@@ -80,6 +81,18 @@ export declare class QueryClient {
    */
   invalidate<TFactory extends QueryFactory>(factory: TFactory, ...args: InputArgs<TFactory>): Promise<void>;
   invalidate(filter: QueryFilter): Promise<void>;
+  /**
+   * Drop queries' data and errors, as if they were never fetched. Read ones
+   * suspend and refetch; resolves once those refetches settle.
+   */
+  reset<TFactory extends QueryFactory>(factory: TFactory, ...args: InputArgs<TFactory>): Promise<void>;
+  reset(filter: QueryFilter): Promise<void>;
+  /**
+   * Remove queries from the cache and abort their requests. Readers keep the
+   * removed entry until they render again.
+   */
+  remove<TFactory extends QueryFactory>(factory: TFactory, ...args: InputArgs<TFactory>): void;
+  remove(filter: QueryFilter): void;
   /** Write data for a factory call. Readers re-render without suspending. */
   setData<TFactory extends QueryFactory>(factory: TFactory, input: InputOf<TFactory>, updater: Updater<DataOf<TFactory>>): void;
   /** Cached data for a factory call, or `undefined`. */

package/dist/client.mjs

@@ -46,6 +46,10 @@ var QueryClient = class {
 			}),
 			defaults: config.defaults ?? {},
 			isServer: this.isServer,
+			observersChanged: (query) => emit({
+				query,
+				type: "observers"
+			}),
 			remove: (query) => {
 				if (this.#cache.get(query.hash) === query) {
 					this.#cache.delete(query.hash);
@@ -109,6 +113,12 @@ var QueryClient = class {
 	async invalidate(target, input) {
 		await Promise.all(this.#match(target, input).map((entry) => entry.invalidate()));
 	}
+	async reset(target, input) {
+		await Promise.all(this.#match(target, input).map((entry) => entry.reset()));
+	}
+	remove(target, input) {
+		for (const entry of this.#match(target, input)) this.#host.remove(entry);
+	}
 	/** Write data for a factory call. Readers re-render without suspending. */
 	setData(factory, input, updater) {
 		const entry = this.#build(factory, input);

package/dist/query.d.mts

@@ -57,7 +57,11 @@ export interface Query<TData = unknown, TFactory extends QueryFactory = QueryFac
   hasNextPage(): boolean;
   hasPreviousPage(): boolean;
   invalidate(): Promise<void>;
+  /** Staleness as of now; `getState().isStale` is only kept current while read. */
+  isStaleNow(): boolean;
   readonly key: QueryKey;
+  /** Readers currently subscribed. */
+  readonly observerCount: number;
   /** Options from the latest factory call; `undefined` for an entry only hydrated so far. */
   readonly options: AnyQueryOptions | undefined;
   /**
@@ -67,6 +71,11 @@ export interface Query<TData = unknown, TFactory extends QueryFactory = QueryFac
   read(): Promise<TData>;
   /** Refetch now; resolves when the request settles. */
   refetch(): Promise<void>;
+  /**
+   * Drop data and errors, back to the state of a new entry. Readers suspend
+   * and refetch; resolves when that refetch settles.
+   */
+  reset(): Promise<void>;
   /** Listen for state changes. Subscribed entries count as read. */
   subscribe(listener: () => void, observer?: QueryObserver): () => void;
 }

package/dist/query.mjs

@@ -95,19 +95,23 @@ var QueryEntry = class {
 	get isObserved() {
 		return this.#listeners.size > 0;
 	}
+	get observerCount() {
+		return this.#listeners.size;
+	}
 	getState = () => this.#state;
-	/** Staleness as of now; `getState().isStale` is only refreshed for read entries. */
 	isStaleNow = () => this.#computeStale(this.#state);
 	subscribe = (listener, observer = defaultObserver) => {
 		this.#listeners.set(listener, observer);
 		this.#clearGc();
 		this.#scheduleStale();
+		this.#host.observersChanged(this);
 		return () => {
-			this.#listeners.delete(listener);
+			if (!this.#listeners.delete(listener)) return;
 			if (this.#listeners.size === 0) {
 				clearTimeout(this.#staleTimer);
 				this.#scheduleGc();
 			}
+			this.#host.observersChanged(this);
 		};
 	};
 	/** Attach the options and input of the latest factory call. */
@@ -158,6 +162,24 @@ var QueryEntry = class {
 		if (!this.isObserved || !this.#options) return Promise.resolve();
 		return this.fetch({ restart: true }).then(noop, noop);
 	};
+	reset = () => {
+		clearTimeout(this.#errorShownTimer);
+		this.#errorShownTimer = void 0;
+		this.#errorShown = false;
+		this.#pending ??= pending();
+		this.#set({
+			data: void 0,
+			error: null,
+			failureCount: 0,
+			hasData: false,
+			isInvalidated: false,
+			promise: this.#pending.promise,
+			status: "pending",
+			updatedAt: 0
+		});
+		if (!this.#options || !this.isObserved && !this.#inFlight) return Promise.resolve();
+		return this.fetch({ restart: true }).then(noop, noop);
+	};
 	/** Write data directly, as if a request had returned it. */
 	setData(data, updatedAt = Date.now()) {
 		this.#succeed(data, updatedAt);

package/package.json

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