@raf-query/react 0.7.8 → 0.7.10

package/CHANGELOG.md

@@ -1,14 +1,31 @@
 # Changelog
 
+## [0.7.10](https://github.com/KATT/raf-query/compare/0.7.9...0.7.10) (2026-10-14)
+
+### Bug Fixes
+
+* **examples:** fit the example apps on a phone screen ([#116](https://github.com/KATT/raf-query/issues/116)) ([1580e00](https://github.com/KATT/raf-query/commit/1580e00f79f4e47e82ddba64e0d22723b9ffb4ba)), references [#112](https://github.com/KATT/raf-query/issues/112)
+* **examples:** open issue pages with prefetch skeletons ([#106](https://github.com/KATT/raf-query/issues/106)) ([db6b5bc](https://github.com/KATT/raf-query/commit/db6b5bcd162dd34073d36c74eaf7618f5012dc31))
+* **examples:** remount the issue page when next or previous changes the id ([#112](https://github.com/KATT/raf-query/issues/112)) ([e4b709b](https://github.com/KATT/raf-query/commit/e4b709b455e4e7bbd85746afe46ecca269a728ee))
+* **react:** type useQuery's promise as Promise ([#118](https://github.com/KATT/raf-query/issues/118)) ([f1b4efe](https://github.com/KATT/raf-query/commit/f1b4efefc7624719b00f0c6e308dd7a72c18c132))
+
+## [0.7.9](https://github.com/KATT/raf-query/compare/0.7.8...0.7.9) (2026-10-14)
+
+- add a Links table to the pull request template ([#108](https://github.com/KATT/raf-query/issues/108)) ([91247e4](https://github.com/KATT/raf-query/commit/91247e47d4d1b4a0b6e5eb2068602629c3fbce9e))
+
+### Features
+
+- QueryClient.runPromise, typed Effect errors, and the Effect RPC example ([#103](https://github.com/KATT/raf-query/issues/103)) ([98bd182](https://github.com/KATT/raf-query/commit/98bd1821081313feb1846531feac0dfbe7215d31)), references [#96](https://github.com/KATT/raf-query/issues/96) [#97](https://github.com/KATT/raf-query/issues/97)
+
 ## [0.7.8](https://github.com/KATT/raf-query/compare/0.7.7...0.7.8) (2026-10-14)
 
-* inline type assertions next to their SAFETY comments ([#104](https://github.com/KATT/raf-query/issues/104)) ([53fdbdb](https://github.com/KATT/raf-query/commit/53fdbdbfdcb146799b145faadb579bbb45e19139))
-* **release:** skip npm publish when packages did not change ([#101](https://github.com/KATT/raf-query/issues/101)) ([4c6c315](https://github.com/KATT/raf-query/commit/4c6c3156224cfb74a62f6c6e5505c30da7400289)), references [#80](https://github.com/KATT/raf-query/issues/80)
-* say the route waits for the post and comments stream in after ([#102](https://github.com/KATT/raf-query/issues/102)) ([3d0c5f4](https://github.com/KATT/raf-query/commit/3d0c5f4c089921fc178b374179dc23bafdbe899c))
+- inline type assertions next to their SAFETY comments ([#104](https://github.com/KATT/raf-query/issues/104)) ([53fdbdb](https://github.com/KATT/raf-query/commit/53fdbdbfdcb146799b145faadb579bbb45e19139))
+- **release:** skip npm publish when packages did not change ([#101](https://github.com/KATT/raf-query/issues/101)) ([4c6c315](https://github.com/KATT/raf-query/commit/4c6c3156224cfb74a62f6c6e5505c30da7400289)), references [#80](https://github.com/KATT/raf-query/issues/80)
+- say the route waits for the post and comments stream in after ([#102](https://github.com/KATT/raf-query/issues/102)) ([3d0c5f4](https://github.com/KATT/raf-query/commit/3d0c5f4c089921fc178b374179dc23bafdbe899c))
 
 ### Bug Fixes
 
-* **examples:** start prefetch off and link whole issue rows ([#105](https://github.com/KATT/raf-query/issues/105)) ([cf83077](https://github.com/KATT/raf-query/commit/cf8307701abc6e6ff50304b7245e3bc2af929f3a))
+- **examples:** start prefetch off and link whole issue rows ([#105](https://github.com/KATT/raf-query/issues/105)) ([cf83077](https://github.com/KATT/raf-query/commit/cf8307701abc6e6ff50304b7245e3bc2af929f3a))
 
 ## [0.7.7](https://github.com/KATT/raf-query/compare/0.7.6...0.7.7) (2026-10-14)
 

package/dist/client.d.mts

@@ -1,5 +1,5 @@
 import { DataOf, DehydrateOptions, DehydratedState, EnsuredQueryHandle, HydrateOptions, InputArgs, InputOf, LoadOptions, PagedQueryFactory, Query, QueryCache, QueryFactory, QueryHandle } from "@raf-query/core";
-import { Layer } from "effect";
+import { Effect, Layer } from "effect";
 //#region src/client.d.ts
 export interface QueryClientConfig<TServices = never> extends QueryCache.Config {
   /**
@@ -10,6 +10,13 @@ export interface QueryClientConfig<TServices = never> extends QueryCache.Config
   readonly layer?: Layer.Layer<TServices>;
   /** Called with every failed request, including failed prefetches. */
   onError?(error: unknown, query: Query.Query): void;
+  /**
+   * When `false`, `useQuery` for an Effect `queryFn` (a typed `ErrorOf`)
+   * returns a `Result` in the first tuple slot instead of a promise that
+   * rejects. Defaults to `false` when `layer` is set, `true` otherwise.
+   * Promise `queryFn`s always throw; this flag does not apply to them.
+   */
+  readonly throwOnError?: boolean;
 }
 /**
  * The query cache, with Promise methods. Create one per request on the
@@ -22,6 +29,11 @@ export declare class QueryClient<TServices = never> {
   /** The Effect-native cache behind this client. */
   readonly effect: QueryCache.QueryCache;
   readonly isServer: boolean;
+  /**
+   * Default for Effect `useQuery` reads. See
+   * {@link QueryClientConfig.throwOnError}.
+   */
+  readonly throwOnError: boolean;
   constructor(config?: QueryClientConfig<TServices>);
   /**
    * The cache entry for a factory call, created if missing. Doesn't fetch.
@@ -91,6 +103,12 @@ export declare class QueryClient<TServices = never> {
    * Returns the matching unmount. Providers call this; mounts are counted.
    */
   mount(): () => void;
+  /**
+   * Run an Effect with the cache (`QueryCache`) and the services of
+   * `config.layer`, as `Effect.runPromise` does: it rejects with the
+   * Effect's failure, or its defect. For an app's loaders and actions.
+   */
+  runPromise<A, E>(effect: Effect.Effect<A, E, QueryCache.QueryCache | TServices>): Promise<A>;
   /**
    * Close the client: interrupt every request and timer, and release the
    * layer's services. Resolves once the layer's finalizers have run.

package/dist/client.mjs

@@ -34,15 +34,27 @@ var QueryClient = class {
 	effect;
 	isServer;
 	/**
+	* Default for Effect `useQuery` reads. See
+	* {@link QueryClientConfig.throwOnError}.
+	*/
+	throwOnError;
+	/**
+	* The cache and the layer's services. Typed `never` so clients of any
+	* `TServices` stay assignable to each other; `runPromise` restores it.
+	*/
+	#context;
+	/**
 	* Owns the cache's fibers, mounts and the layer's services; lives until
 	* `dispose()`.
 	*/
 	#scope = Scope.makeUnsafe();
 	constructor(config = {}) {
 		const cache = QueryCache.layer(config);
-		const services = Effect.runSync(Layer.buildWithScope(config.layer ? Layer.provide(cache, config.layer) : cache, this.#scope));
+		const services = Effect.runSync(Layer.buildWithScope(config.layer ? Layer.provideMerge(cache, config.layer) : cache, this.#scope));
+		this.#context = services;
 		this.effect = Context.get(services, QueryCache.QueryCache);
 		this.isServer = this.effect.isServer;
+		this.throwOnError = config.throwOnError ?? config.layer === void 0;
 		const onError = config.onError;
 		if (onError) this.effect.subscribeUnsafe((event) => {
 			if (event.type === "failed") onError(event.error, event.query);
@@ -134,6 +146,14 @@ var QueryClient = class {
 		};
 	}
 	/**
+	* Run an Effect with the cache (`QueryCache`) and the services of
+	* `config.layer`, as `Effect.runPromise` does: it rejects with the
+	* Effect's failure, or its defect. For an app's loaders and actions.
+	*/
+	runPromise(effect) {
+		return Effect.runPromiseWith(this.#context)(effect);
+	}
+	/**
 	* Close the client: interrupt every request and timer, and release the
 	* layer's services. Resolves once the layer's finalizers have run.
 	*/

package/dist/index.d.mts

@@ -2,7 +2,7 @@ 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 { HasTypedError, PagingControls, QueryControls, ThrowsOnError, UseEnsuredQueryResult, UseQueryControls, UseQueryOptions, UseQueryResult, UseQueryThrowOptions, 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, useIsFetching, useQuery, useQueryClient, useWaterfall };
+export { type HasTypedError, type PagingControls, QueryClient, type QueryClientConfig, QueryClientProvider, type QueryControls, type Settled, type ThrowsOnError, type UseEnsuredQueryResult, type UseQueryControls, type UseQueryOptions, type UseQueryResult, type UseQueryThrowOptions, allKeyed, dehydrate, hydrate, useIsFetching, useQuery, useQueryClient, useWaterfall };

package/dist/use-query.d.mts

@@ -1,8 +1,23 @@
 import "./client.mjs";
-import { DataOf, EnsuredQueryHandle, InputOf, IsPaged, Query, QueryFactory, QueryHandle, QueryKey, QueryObserver, Thenable } from "@raf-query/core";
+import { DataOf, EnsuredQueryHandle, ErrorOf, InputOf, IsPaged, Query, QueryFactory, QueryHandle, QueryKey, QueryObserver } from "@raf-query/core";
+import { Result } from "effect";
 //#region src/use-query.d.ts
 /** `refetchInterval`, `refetchOnWindowFocus`, `refetchOnReconnect`, `whilePending`. */
 export type UseQueryOptions = QueryObserver.Options;
+/**
+ * `throwOnError` only when {@link ErrorOf} is typed (Effect `queryFn`).
+ * Promise factories always throw; the option is not part of their options.
+ */
+export type UseQueryThrowOptions<TFactory extends QueryFactory> = HasTypedError<TFactory> extends true ? {
+  /**
+   * When `false`, the first tuple slot is a `Result` instead of a
+   * rejecting promise. Omit to use the client's default (`false`
+   * with a `layer`, `true` without).
+   */
+  readonly throwOnError?: boolean;
+} : {
+  readonly throwOnError?: never;
+};
 /** The second element of {@link useQuery}'s result. */
 export interface QueryControls<TFactory extends QueryFactory> {
   /** Error of the last failed request. Existing data stays readable. */
@@ -36,9 +51,21 @@ export interface PagingControls {
   readonly isFetchingPreviousPage: boolean;
 }
 export type UseQueryControls<TFactory extends QueryFactory> = IsPaged<TFactory> extends true ? QueryControls<TFactory> & PagingControls : QueryControls<TFactory>;
-export type UseQueryResult<TFactory extends QueryFactory> = readonly [promise: Thenable<DataOf<TFactory>>, controls: UseQueryControls<TFactory>];
+/**
+ * `true` when the factory's error channel is typed (Effect `queryFn`), not
+ * `unknown` (promise / plain value).
+ */
+export type HasTypedError<TFactory extends QueryFactory> = unknown extends ErrorOf<TFactory> ? false : true;
+/**
+ * Whether this read throws on failure. Untyped errors always throw. Typed
+ * errors follow `options.throwOnError`, else the client's default (`false`
+ * with a `layer`, `true` without). Types treat an omitted flag as `false`
+ * (Result), matching a client with a `layer`.
+ */
+export type ThrowsOnError<TFactory extends QueryFactory, TThrow extends boolean | undefined> = HasTypedError<TFactory> extends false ? true : TThrow extends boolean ? TThrow : false;
+export type UseQueryResult<TFactory extends QueryFactory, TThrow extends boolean | undefined = undefined> = ThrowsOnError<TFactory, TThrow> extends true ? readonly [promise: Promise<DataOf<TFactory>>, controls: UseQueryControls<TFactory>] : readonly [promise: Promise<Result.Result<DataOf<TFactory>, ErrorOf<TFactory>>>, controls: UseQueryControls<TFactory>];
 /** {@link useQuery}'s result for a handle from `ensure`. */
-export type UseEnsuredQueryResult<TFactory extends QueryFactory> = readonly [data: DataOf<TFactory>, controls: UseQueryControls<TFactory>];
+export type UseEnsuredQueryResult<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>];
 /**
  * Read the query a handle points at. Returns a promise to unwrap with
  * `use()` and the query's controls:
@@ -48,13 +75,23 @@ export type UseEnsuredQueryResult<TFactory extends QueryFactory> = readonly [dat
  * const post = use(postPromise);
  * ```
  *
+ * For an Effect `queryFn` (typed {@link ErrorOf}), with the client's
+ * `throwOnError: false` (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 handle from `ensure` had its data loaded before the route rendered, so
- * the hook returns the data itself:
+ * the hook returns the data (or `Result`) itself:
  *
  * ```tsx
  * const [post, postState] = useQuery(postQuery, loaderData.post);
@@ -63,6 +100,10 @@ export type UseEnsuredQueryResult<TFactory extends QueryFactory> = readonly [dat
  * If that entry has lost its data since (garbage-collected, `reset`), the
  * hook suspends until it is refetched.
  */
-export declare function useQuery<TFactory extends QueryFactory>(factory: TFactory, handle: EnsuredQueryHandle<TFactory>, options?: UseQueryOptions): UseEnsuredQueryResult<TFactory>;
-export declare function useQuery<TFactory extends QueryFactory>(factory: TFactory, handle: QueryHandle<TFactory>, options?: UseQueryOptions): UseQueryResult<TFactory>;
+export declare function useQuery<TFactory extends QueryFactory, const TThrow extends boolean | undefined = undefined>(factory: TFactory, handle: EnsuredQueryHandle<TFactory>, options?: UseQueryOptions & UseQueryThrowOptions<TFactory> & {
+  readonly throwOnError?: TThrow;
+}): UseEnsuredQueryResult<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>;
 //#endregion

package/dist/use-query.mjs

@@ -1,8 +1,8 @@
 "use client";
 import { useQueryClient } from "./provider.mjs";
 import { assertSent } from "./browser-requests.mjs";
-import { Query, QueryObserver } from "@raf-query/core";
-import { Effect } from "effect";
+import { Query, QueryObserver, fulfilled, pending } from "@raf-query/core";
+import { Effect, Result } from "effect";
 import { use, useEffect, useState, useSyncExternalStore } from "react";
 //#region src/use-query.ts
 function queryFor(client, factory, input) {
@@ -34,6 +34,29 @@ function storeFor(query, options) {
 		subscribe: (onChange) => QueryObserver.subscribeUnsafe(observer, onChange)
 	};
 }
+/**
+* One `Result` thenable per data thenable, so `use()` sees a stable identity
+* across re-renders the same way it does for the data promise.
+*/
+const resultThenables = /* @__PURE__ */ new WeakMap();
+function asResultThenable(promise) {
+	const cached = resultThenables.get(promise);
+	if (cached) return cached;
+	let next;
+	if (promise.status === "fulfilled") next = fulfilled(Result.succeed(promise.value));
+	else if (promise.status === "rejected") next = fulfilled(Result.fail(promise.reason));
+	else {
+		const deferred = pending();
+		promise.then((value) => {
+			deferred.resolve(Result.succeed(value));
+		}, (error) => {
+			deferred.resolve(Result.fail(error));
+		});
+		next = deferred.promise;
+	}
+	resultThenables.set(promise, next);
+	return next;
+}
 function useQuery(factory, handle, options = {}) {
 	const client = useQueryClient();
 	const query = queryFor(client, factory, handle.input);
@@ -64,6 +87,11 @@ function useQuery(factory, handle, options = {}) {
 	]);
 	QueryObserver.trackProp(observer, "promise");
 	const controls = withPromiseCommands(QueryObserver.trackResult(observer, result));
+	if (!(options.throwOnError ?? client.throwOnError)) {
+		const resultPromise = asResultThenable(result.promise);
+		if (handle.ensured === true) return [use(resultPromise), controls];
+		return [resultPromise, controls];
+	}
 	if (handle.ensured === true) return [use(result.promise), controls];
 	return [result.promise, controls];
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@raf-query/react",
-  "version": "0.7.8",
+  "version": "0.7.10",
   "description": "React bindings for raf-query, a render-as-you-fetch query library",
   "keywords": [
     "query",
@@ -46,7 +46,7 @@
     }
   },
   "dependencies": {
-    "@raf-query/core": "0.7.8"
+    "@raf-query/core": "0.7.10"
   },
   "peerDependencies": {
     "@tanstack/react-router": "^1.170.0",