@raf-query/react 0.11.1 → 0.12.0

package/dist/use-is-fetching.mjs

@@ -1,40 +1,20 @@
-"use client";
 import { useQueryClient } from "./provider.mjs";
+import { isFetching } from "@raf-query/core";
 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;
+const serverCount = () => 0;
 /**
-* How many queries have a request in flight: all of them, or those matching
-* `filter`. Re-renders when the count changes. It's `0` on the server and
-* while hydrating, so the server's HTML and the browser's first render agree.
-*
-* You probably don't need this. Prefer the router's pending UI for
-* navigations (`useRouterState` / `pendingComponent` in TanStack Router,
-* `useLinkStatus` in Next.js) and per-query `controls.isFetching` for
-* background refetches. Kept for TanStack Query compatibility when you want
-* one global count of every in-flight request:
-*
-* ```tsx
-* const fetching = useIsFetching();
-* return fetching > 0 ? <ProgressBar /> : null;
-* ```
+* How many queries have a request in flight: all of them, or a factory's,
+* a group's or a target's. For a global loading indicator. Always `0` on
+* the server and while hydrating, so the HTML matches the first browser render.
 */
-function useIsFetching(filter) {
+function useIsFetching(target) {
 	const client = useQueryClient();
-	const subscribe = useCallback((onStoreChange) => subscribeDeferred(client, onStoreChange), [client]);
-	const getSnapshot = () => client.isFetching(filter);
-	return useSyncExternalStore(subscribe, getSnapshot, none);
+	const subscribe = useCallback((onChange) => client.subscribe((event) => {
+		if (event.type === "updated" || event.type === "removed") onChange();
+	}), [client]);
+	const count = () => isFetching(client, target);
+	return useSyncExternalStore(subscribe, count, serverCount);
 }
 //#endregion
 export { useIsFetching };

package/dist/use-query.d.mts

@@ -1,62 +1,51 @@
-import { DataOf, ErrorOf, QueryFactory, QueryHandle, QueryHandleWithData, Thenable, ThrowsOnError, UseQueryControls, UseQueryOptions, UseQueryThrowOptions } from "@raf-query/core";
-import { Result } from "effect";
+import "./tracked.mjs";
+import { DataOf, InputOf, QueryFactory, QueryHandle, SingleQueryFactory, Thenable } from "@raf-query/core";
+import "@raf-query/core/internal";
 //#region src/use-query.d.ts
-export type UseQueryResult<TFactory extends QueryFactory, TThrow extends boolean | undefined = undefined> = ThrowsOnError<TFactory, TThrow> extends true ? readonly [promise: Thenable<DataOf<TFactory>>, controls: UseQueryControls<TFactory>] : readonly [promise: Thenable<Result.Result<DataOf<TFactory>, ErrorOf<TFactory>>>, controls: UseQueryControls<TFactory>];
-/** {@link useQuery}'s result for a handle from `ensure` or `fetch`. */
-export type UseQueryResultWithData<TFactory extends QueryFactory, TThrow extends boolean | undefined = undefined> = ThrowsOnError<TFactory, TThrow> extends true ? readonly [data: DataOf<TFactory>, controls: UseQueryControls<TFactory>] : readonly [result: Result.Result<DataOf<TFactory>, ErrorOf<TFactory>>, controls: UseQueryControls<TFactory>];
+export interface UseQueryOptions {
+  /**
+   * While a new handle's query has no data: `"suspend"` (the default) shows
+   * the Suspense fallback; `"previous"` keeps showing the last handle's data
+   * and sets `isPrevious`.
+   */
+  readonly whilePending?: "previous" | "suspend";
+}
+/** What `useQuery` returns next to the data. */
+export interface QueryState<TFactory extends QueryFactory = QueryFactory> {
+  /** The last request's error while it's the latest outcome. */
+  readonly error: unknown;
+  readonly hash: string;
+  readonly input: InputOf<TFactory>;
+  readonly isFetching: boolean;
+  /** No data yet. */
+  readonly isPending: boolean;
+  /** Showing the previous handle's data (`whilePending: "previous"`). */
+  readonly isPrevious: boolean;
+  readonly isStale: boolean;
+  readonly queryKey: ReturnType<TFactory>["queryKey"];
+  /** Fetch again, or join the request in flight. Resolves when it settles. */
+  refetch(): Promise<void>;
+  /** When the data was fetched (ms since epoch); `0` without data. */
+  readonly updatedAt: number;
+}
 /**
- * Read the query a handle points at. Returns a promise to unwrap with
- * `use()` and the query's controls:
- *
- * ```tsx
- * const [postPromise, postState] = useQuery(postQuery, loaderData.post);
- * const post = use(postPromise);
- * ```
- *
- * For an Effect `queryFn` (typed {@link ErrorOf}), with `throwOnError: false`
- * (the call's, else the query's, else the client's, which is the default
- * when it has a `layer`), the first slot is a `Result` instead — `use()`
- * never throws:
- *
- * ```tsx
- * const [issueResult, issueState] = useQuery(issueQuery, loaderData.issue);
- * const issue = use(issueResult);
- * Result.match(issue, { onFailure: …, onSuccess: … });
- * ```
- *
- * The promise is stable per data version and already fulfilled once the
- * cache has data, so `use()` only suspends while there is nothing to show.
- * The component re-renders when the promise changes, and when a control it
- * has read changes; changes to controls it never reads are skipped. A
- * first load settles its pending promise in place: that counts as a change
- * once the component has read the promise's `status`, `value` or `reason`,
- * so reading them without `use()` re-renders when the data lands:
- *
- * ```tsx
- * const [tagPromise] = useQuery(tagQuery, loaderData.tag);
- * const tag = tagPromise.status === "fulfilled" ? tagPromise.value : "…";
- * ```
- *
- * A handle from `ensure` or `fetch` already has its data, so the hook
- * unwraps the promise itself and returns the data (or `Result`):
+ * What `useQuery` and `useInfiniteQuery` read, for every handle: a thenable
+ * to pass to `use()`.
+ * A loader can't promise the data is still cached when a component renders
+ * (a write can reset or remove it), so the read may suspend.
+ */
+export type QueryValue<TFactory extends QueryFactory> = Thenable<DataOf<TFactory>>;
+/**
+ * Read a query by its handle.
  *
  * ```tsx
- * const [post, postState] = useQuery(postQuery, loaderData.post);
+ * const [issueThenable, issueState] = useQuery(issueQuery, handles.issue);
+ * const issue = use(issueThenable);
  * ```
  *
- * It reads the live entry, not the handle's `data` snapshot. If that entry
- * has lost its data since (garbage-collected, `reset`), the hook suspends
- * until it is refetched.
- *
- * The hook picks by the handle at runtime (`data` in it), so a prop that
- * receives a handle from `ensure` / `fetch` must be typed
- * {@link QueryHandleWithData}: typed as `QueryHandle`, it reads as a promise
- * while the hook returns the data.
+ * Reading never refetches stale data: loaders decide freshness. A query no
+ * loader started fetches while rendering, which is a waterfall (see
+ * `waterfallHandle`). Paged queries read with `useInfiniteQuery`.
  */
-export declare function useQuery<TFactory extends QueryFactory, const TThrow extends boolean | undefined = undefined>(factory: TFactory, handle: QueryHandleWithData<TFactory>, options?: UseQueryOptions & UseQueryThrowOptions<TFactory> & {
-  readonly throwOnError?: TThrow;
-}): UseQueryResultWithData<TFactory, TThrow>;
-export declare function useQuery<TFactory extends QueryFactory, const TThrow extends boolean | undefined = undefined>(factory: TFactory, handle: QueryHandle<TFactory>, options?: UseQueryOptions & UseQueryThrowOptions<TFactory> & {
-  readonly throwOnError?: TThrow;
-}): UseQueryResult<TFactory, TThrow>;
+export declare function useQuery<TFactory extends SingleQueryFactory>(factory: TFactory, handle: QueryHandle<TFactory>, options?: UseQueryOptions): readonly [QueryValue<TFactory>, QueryState<TFactory>];
 //#endregion

package/dist/use-query.mjs

@@ -1,56 +1,111 @@
-"use client";
 import { useQueryClient } from "./provider.mjs";
-import { assertSent } from "./query-provider/browser-requests.mjs";
-import { Query, QueryBinding, QueryObserver, promiseControls, resultThenable, throwsOnError } from "@raf-query/core";
-import { use, useEffect, useState, useSyncExternalStore } from "react";
+import { browserRender, leavesUnstartedToBrowser } from "./browser-render.mjs";
+import { createTracker, renderedChanged, trackedState } from "./tracked.mjs";
+import { entryOf, fetchEntry, isInvalidated, isStale, isWaterfallHandle, mapThenable, subscribeEntry } from "@raf-query/core/internal";
+import { useCallback, useState, useSyncExternalStore } from "react";
 //#region src/use-query.ts
-function storeFor(query, options) {
-	const observer = QueryObserver.makeUnsafe(query, options);
+/** Whether nothing is loading the entry: no data, no error, no request in flight. */
+function isIdle(entry, state) {
+	return !state.hasData && !entry.run && state.status !== "error";
+}
+/**
+* Start the request of an entry nothing is loading: the reader of a
+* waterfall handle, or of a query the cache dropped. A server render fed by
+* server components leaves it to the browser: nothing would send its data.
+*/
+function startIfMissing(entry, state, waterfall) {
+	const client = entry.client;
+	if (!isIdle(entry, state) || leavesUnstartedToBrowser(client)) return;
+	if (process.env.NODE_ENV !== "production" && !waterfall && !client.isServer) console.warn(`raf-query: ${entry.hash} was read before anything loaded it, so it fetches while rendering. Start it in a loader with load(), or build the handle with waterfallHandle() to make the waterfall explicit.`);
+	fetchEntry(entry);
+}
+/**
+* In a server render fed by server components, an entry `startIfMissing`
+* left to the browser reads as a rejection: a `use()` of it inside Suspense
+* renders that boundary's fallback, and the browser renders the content.
+*/
+function readOf(entry, state) {
+	return leavesUnstartedToBrowser(entry.client) && isIdle(entry, state) ? browserRender(entry) : entry.thenable;
+}
+function settled(promise) {
+	return promise.then(() => {});
+}
+/**
+* One read of the entry. It takes both entries' states as arguments: core
+* writes a new state object with every write (and the thenable that
+* carries it), so a compiler that memoizes the call recomputes it.
+*/
+function readQuery(current, state, shown, shownState, handle, options, extra) {
+	const isPrevious = options?.whilePending === "previous" && !state.hasData && shown !== current && shownState.hasData;
+	const entry = isPrevious ? shown : current;
+	const entryState = isPrevious ? shownState : state;
+	const added = extra?.(entry, entryState);
 	return {
-		getSnapshot: () => QueryObserver.getUnsafe(observer),
-		observer,
-		subscribe: (onChange) => QueryObserver.subscribeUnsafe(observer, onChange)
+		actions: {
+			refetch: () => settled(fetchEntry(current)),
+			...added?.actions
+		},
+		entry,
+		fields: {
+			error: state.error,
+			hash: current.hash,
+			input: handle.input,
+			isFetching: state.isFetching,
+			isPending: !state.hasData,
+			isPrevious,
+			isStale: isStale(current),
+			queryKey: handle.queryKey,
+			updatedAt: state.updatedAt,
+			...added?.fields
+		},
+		source: readOf(entry, entryState)
 	};
 }
-function useQuery(factory, handle, options = {}) {
+/**
+* The read both hooks share: the thenable, and the state with the fields
+* `extra` adds. The state is tracked: the component re-renders, and gets a
+* new state object, only when the thenable or a field it read changes.
+*/
+function useQueryRead(factory, handle, options, extra) {
 	const client = useQueryClient();
-	const query = QueryBinding.queryFor(client, factory, handle);
-	assertSent(client, query);
-	Query.readUnsafe(query);
-	const refetchInterval = options.refetchInterval;
-	const refetchOnReconnect = options.refetchOnReconnect;
-	const refetchOnWindowFocus = options.refetchOnWindowFocus;
-	const whilePending = options.whilePending;
-	const [store] = useState(() => storeFor(query, options));
-	const observer = store.observer;
-	const result = QueryObserver.getOptimisticResultUnsafe(observer, query, options);
-	useSyncExternalStore(store.subscribe, store.getSnapshot, store.getSnapshot);
-	useEffect(() => {
-		QueryObserver.setOptionsUnsafe(observer, query, {
-			refetchInterval,
-			refetchOnReconnect,
-			refetchOnWindowFocus,
-			whilePending
+	const current = entryOf(client, factory, handle.input);
+	const [tracker] = useState(createTracker);
+	const subscribe = useCallback((onChange) => {
+		const unsubscribe = subscribeEntry(current, () => {
+			if (renderedChanged(tracker)) onChange();
 		});
-	}, [
-		observer,
-		query,
-		refetchInterval,
-		refetchOnReconnect,
-		refetchOnWindowFocus,
-		whilePending
-	]);
-	QueryObserver.trackProp(observer, "promise");
-	const controls = promiseControls(QueryObserver.trackResult(observer, result));
-	const throwOnError = throwsOnError(query, options.throwOnError, client.throwOnError);
-	const withData = "data" in handle;
-	if (!throwOnError) {
-		const resultPromise = resultThenable(result.promise);
-		if (withData) return [use(resultPromise), controls];
-		return [QueryObserver.trackThenable(observer, resultPromise), controls];
-	}
-	if (withData) return [use(result.promise), controls];
-	return [QueryObserver.trackThenable(observer, result.promise), controls];
+		if (isInvalidated(current)) fetchEntry(current);
+		return unsubscribe;
+	}, [current, tracker]);
+	const getState = () => current.state;
+	const state = useSyncExternalStore(subscribe, getState, getState);
+	const [shown, setShown] = useState(current);
+	if (shown !== current && state.hasData) setShown(current);
+	startIfMissing(current, state, isWaterfallHandle(handle));
+	const read = readQuery(current, state, shown, shown.state, handle, options, extra);
+	const controls = trackedState(tracker, read, () => readQuery(current, current.state, shown, shown.state, handle, options, extra));
+	const selected = useState(() => /* @__PURE__ */ new WeakMap())[0];
+	const select = read.entry.options?.select;
+	return {
+		controls,
+		thenable: select ? mapThenable(selected, read.source, select) : read.source
+	};
+}
+/**
+* Read a query by its handle.
+*
+* ```tsx
+* const [issueThenable, issueState] = useQuery(issueQuery, handles.issue);
+* const issue = use(issueThenable);
+* ```
+*
+* Reading never refetches stale data: loaders decide freshness. A query no
+* loader started fetches while rendering, which is a waterfall (see
+* `waterfallHandle`). Paged queries read with `useInfiniteQuery`.
+*/
+function useQuery(factory, handle, options) {
+	const read = useQueryRead(factory, handle, options);
+	return [read.thenable, read.controls];
 }
 //#endregion
-export { useQuery };
+export { settled, useQuery, useQueryRead };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@raf-query/react",
-  "version": "0.11.1",
+  "version": "0.12.0",
   "description": "React bindings for raf-query, a render-as-you-fetch query library",
   "keywords": [
     "query",
@@ -36,7 +36,6 @@
       "react-server": "./dist/index-react-server.mjs",
       "default": "./dist/index.mjs"
     },
-    "./devtools": "./dist/devtools.mjs",
     "./tanstack-router": {
       "workerd": "./dist/tanstack-router.mjs",
       "worker": "./dist/tanstack-router.mjs",
@@ -48,11 +47,10 @@
     }
   },
   "dependencies": {
-    "@raf-query/core": "0.11.1"
+    "@raf-query/core": "0.12.0"
   },
   "peerDependencies": {
     "@tanstack/react-router": "^1.170.0",
-    "effect": "^4.0.0",
     "react": "^19.2.0"
   },
   "peerDependenciesMeta": {
@@ -61,19 +59,22 @@
     }
   },
   "devDependencies": {
-    "@effect/vitest": "4.0.1",
+    "@babel/core": "7.29.7",
+    "@rolldown/plugin-babel": "0.2.4",
     "@tanstack/react-router": "1.170.42",
     "@testing-library/react": "16.3.3",
     "@types/node": "26.6.4",
     "@types/react": "19.3.0",
     "@types/react-dom": "19.3.0",
+    "@vitejs/plugin-react": "6.1.2",
     "@vitest/coverage-v8": "5.0.1",
-    "effect": "^4.0.1",
+    "babel-plugin-react-compiler": "1.0.0",
     "happy-dom": "21.0.1",
     "react": "19.3.0",
     "react-dom": "19.3.0",
     "typescript": "7.0.2",
-    "vite-plus": "1.0.0"
+    "vite-plus": "1.0.0",
+    "vitest": "5.0.1"
   },
   "publishConfig": {
     "access": "public",
@@ -84,8 +85,8 @@
   },
   "scripts": {
     "build": "vp pack",
-    "test": "vp test",
-    "typecheck": "tsc",
+    "test": "vp test --config vitest.compiler.config.ts && vp test",
+    "typecheck": "tsc && tsc -p tsconfig.no-node.json",
     "publish:npm": "pnpm pack --out package.tgz && npm publish package.tgz --access public && rm package.tgz"
   }
 }

package/dist/devtools-panel.d.mts

@@ -1,38 +0,0 @@
-import { QueryClient } from "@raf-query/core";
-import { CSSProperties } from "react";
-//#region src/devtools-panel.d.ts
-export type DevtoolsTheme = "dark" | "light" | "system";
-export interface QueryDevtoolsPanelProps {
-  /** The client to inspect. Default: the nearest `QueryClientProvider`'s. */
-  readonly client?: QueryClient;
-  /** Shows a close button that calls this. */
-  readonly onClose?: () => void;
-  /** Styles for the panel's root element, e.g. its height. */
-  readonly style?: CSSProperties;
-  /** Default: `"system"`. */
-  readonly theme?: DevtoolsTheme;
-}
-export interface QueryDevtoolsProps {
-  /** Corner of the toggle button. Default: `"bottom-right"`. */
-  readonly buttonPosition?: "bottom-left" | "bottom-right" | "top-left" | "top-right";
-  /** The client to inspect. Default: the nearest `QueryClientProvider`'s. */
-  readonly client?: QueryClient;
-  /** Open on the first visit. Later visits remember the last open state. */
-  readonly initialIsOpen?: boolean;
-  /** Edge of the viewport the panel docks to. Default: `"bottom"`. */
-  readonly position?: "bottom" | "left" | "right" | "top";
-  /** Default: `"system"`. */
-  readonly theme?: DevtoolsTheme;
-}
-/**
- * The devtools panel on its own, to place anywhere in the page. Renders
- * nothing on the server, since the server's cache isn't the browser's.
- */
-export declare function QueryDevtoolsPanel(props: QueryDevtoolsPanelProps): import("react").JSX.Element | null;
-/**
- * A toggle button that opens the devtools panel docked to an edge of the
- * viewport. Renders nothing on the server. Open state and size are kept in
- * `localStorage`.
- */
-export declare function QueryDevtools(props: QueryDevtoolsProps): import("react").JSX.Element | null;
-//#endregion