@raf-query/core 0.11.0 → 0.11.1

package/CHANGELOG.md

@@ -1,14 +1,20 @@
 # Changelog
 
+## [0.11.1](https://github.com/KATT/raf-query/compare/0.11.0...0.11.1) (2026-10-17)
+
+### Features
+
+* **core:** take throwOnError from the query's options (2/2) ([#214](https://github.com/KATT/raf-query/issues/214)) ([ef1f0fd](https://github.com/KATT/raf-query/commit/ef1f0fd8eda2a73f4c4c268e8a3a5cf91a0ba0d8)), references [#448](https://github.com/KATT/raf-query/issues/448)
+
 ## [0.11.0](https://github.com/KATT/raf-query/compare/0.10.4...0.11.0) (2026-10-16)
 
 ### ⚠ BREAKING CHANGES
 
-* **core:** enabled replaces ssr, as a boolean like TanStack Query's ([#204](https://github.com/KATT/raf-query/issues/204))
+- **core:** enabled replaces ssr, as a boolean like TanStack Query's ([#204](https://github.com/KATT/raf-query/issues/204))
 
 ### Features
 
-* **core:** enabled replaces ssr, as a boolean like TanStack Query's ([#204](https://github.com/KATT/raf-query/issues/204)) ([b7e543b](https://github.com/KATT/raf-query/commit/b7e543b9d1d34e02061740f749f2ddabcdee2ad2))
+- **core:** enabled replaces ssr, as a boolean like TanStack Query's ([#204](https://github.com/KATT/raf-query/issues/204)) ([b7e543b](https://github.com/KATT/raf-query/commit/b7e543b9d1d34e02061740f749f2ddabcdee2ad2))
 
 ## [0.10.4](https://github.com/KATT/raf-query/compare/0.10.3...0.10.4) (2026-10-16)
 

package/dist/binding.mjs

@@ -1,7 +1,7 @@
 import { __exportAll } from "./_virtual/_rolldown/runtime.mjs";
 import { hashKey } from "./key.mjs";
 import { readUnsafe } from "./query.mjs";
-import { promiseControls, resultThenable } from "./controls.mjs";
+import { promiseControls, resultThenable, throwsOnError } from "./controls.mjs";
 import { getOptimisticResultUnsafe, getUnsafe, makeUnsafe as makeUnsafe$1, setOptionsUnsafe, subscribeUnsafe as subscribeUnsafe$1, trackProp } from "./observer.mjs";
 import { Result } from "effect";
 //#region src/binding.ts
@@ -113,7 +113,7 @@ function resultOf(impl) {
 		return impl.client.isServer ? getOptimisticResultUnsafe(observer, impl.query, impl.options) : getUnsafe(observer);
 	}
 	function throwOnError() {
-		return impl.source.options().throwOnError ?? impl.client.throwOnError;
+		return throwsOnError(impl.query, impl.source.options().throwOnError, impl.client.throwOnError);
 	}
 	function shown() {
 		const promise = read("promise").promise;

package/dist/client.d.mts

@@ -17,8 +17,10 @@ export interface QueryClientConfig<TServices = never> extends Config {
    * 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, whatever this flag says: reads tell
-   * them apart by what the `queryFn` returned ({@link Query.returnsEffectUnsafe}).
+   * A query's own `throwOnError` (in `queryOptions`) and a read's win over
+   * it; types only see those two. Promise `queryFn`s always throw, whatever
+   * the flags say: reads tell them apart by what the `queryFn` returned
+   * ({@link Query.returnsEffectUnsafe}).
    */
   readonly throwOnError?: boolean;
 }

package/dist/controls.d.mts

@@ -1,5 +1,5 @@
 import { QueryKey } from "./key.mjs";
-import { DataOf, ErrorOf, InputOf, IsPaged, QueryFactory } from "./options.mjs";
+import { DataOf, ErrorOf, InputOf, IsPaged, QueryFactory, ThrowOnErrorOf } from "./options.mjs";
 import { Thenable } from "./thenable.mjs";
 import { Query, query_d_exports } from "./query.mjs";
 import { Options, Result as Result$1, observer_d_exports } from "./observer.mjs";
@@ -14,8 +14,8 @@ export type UseQueryOptions = Options;
 export type UseQueryThrowOptions<TFactory extends QueryFactory> = HasTypedError<TFactory> extends true ? {
   /**
    * When `false`, the data is a `Result` instead of a rejecting
-   * promise. Omit to use the client's default (`false` with a
-   * `layer`, `true` without).
+   * promise. Omit to use the query's `throwOnError`, else the
+   * client's default (`false` with a `layer`, `true` without).
    */
   readonly throwOnError?: boolean;
 } : {
@@ -61,18 +61,20 @@ export type UseQueryControls<TFactory extends QueryFactory> = IsPaged<TFactory>
 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`.
+ * errors follow the read's `throwOnError`, else the query's
+ * ({@link ThrowOnErrorOf}), else the client's default (`false` with a
+ * `layer`, `true` without). Types can't see the client's, so they treat it
+ * 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 ThrowsOnError<TFactory extends QueryFactory, TThrow extends boolean | undefined> = HasTypedError<TFactory> extends false ? true : TThrow extends boolean ? TThrow : ThrowOnErrorOf<TFactory> extends boolean ? ThrowOnErrorOf<TFactory> : false;
 /**
  * {@link ThrowsOnError} at runtime, for bindings: a read of `query` throws
- * when `throwOnError` (the call's, else the client's) is `true`, or when its
- * `queryFn` returns a promise or plain value, whose error isn't typed. A
- * query whose `queryFn` hasn't run yet follows `throwOnError`.
+ * when its `queryFn` returns a promise or plain value, whose error isn't
+ * typed. Otherwise it follows the read's `throwOnError`, else the query's
+ * options', else `clientDefault` (pass the client's `throwOnError`). A query
+ * whose `queryFn` hasn't run yet follows the flags.
  */
-export declare function throwsOnError<TFactory extends QueryFactory>(query: Query<TFactory>, throwOnError: boolean): boolean;
+export declare function throwsOnError<TFactory extends QueryFactory>(query: Query<TFactory>, throwOnError: boolean | undefined, clientDefault?: boolean): boolean;
 /** What a read settles with: the data, or a `Result` when it doesn't throw. */
 export type ReadValue<TFactory extends QueryFactory, TThrow extends boolean | undefined = undefined> = ThrowsOnError<TFactory, TThrow> extends true ? DataOf<TFactory> : Result.Result<DataOf<TFactory>, ErrorOf<TFactory>>;
 type Command = "fetchNextPage" | "fetchPreviousPage" | "refetch";

package/dist/controls.mjs

@@ -9,12 +9,13 @@ import { Effect, Result } from "effect";
 */
 /**
 * {@link ThrowsOnError} at runtime, for bindings: a read of `query` throws
-* when `throwOnError` (the call's, else the client's) is `true`, or when its
-* `queryFn` returns a promise or plain value, whose error isn't typed. A
-* query whose `queryFn` hasn't run yet follows `throwOnError`.
+* when its `queryFn` returns a promise or plain value, whose error isn't
+* typed. Otherwise it follows the read's `throwOnError`, else the query's
+* options', else `clientDefault` (pass the client's `throwOnError`). A query
+* whose `queryFn` hasn't run yet follows the flags.
 */
-function throwsOnError(query, throwOnError) {
-	return throwOnError || returnsEffectUnsafe(query) === false;
+function throwsOnError(query, throwOnError, clientDefault = false) {
+	return returnsEffectUnsafe(query) === false || (throwOnError ?? query.options?.throwOnError ?? clientDefault);
 }
 const commands = /* @__PURE__ */ new WeakMap();
 /** One stable Promise function per command Effect, so identities track the query's. */

package/dist/index.d.mts

@@ -1,6 +1,6 @@
 import { Settled, allKeyed } from "./all-keyed.mjs";
 import { QueryKey, hashKey, matchesKey } from "./key.mjs";
-import { AnyQueryOptions, DataOf, ErrorOf, InfiniteData, InfiniteQueryOptions, InfiniteQueryTypes, InputArgs, InputOf, IsPaged, LoadOptions, PageFunctionContext, PageOf, PagedQueryFactory, QueryBehavior, QueryFactory, QueryFnResult, QueryFunctionContext, QueryHandle, QueryHandleWithData, QueryMeta, QueryOptions, QueryTypes, Register, RetryPolicy, ServicesOf, infiniteQueryOptions, queryOptions } from "./options.mjs";
+import { AnyQueryOptions, DataOf, ErrorOf, InfiniteData, InfiniteQueryOptions, InfiniteQueryTypes, InputArgs, InputOf, IsPaged, LoadOptions, PageFunctionContext, PageOf, PagedQueryFactory, QueryBehavior, QueryFactory, QueryFnResult, QueryFunctionContext, QueryHandle, QueryHandleWithData, QueryMeta, QueryOptions, QueryTypes, Register, RetryPolicy, ServicesOf, ThrowOnErrorOf, infiniteQueryOptions, queryOptions } from "./options.mjs";
 import { platform_d_exports } from "./platform.mjs";
 import { Pending, Thenable, fulfilled, pending } from "./thenable.mjs";
 import { query_d_exports } from "./query.mjs";
@@ -10,4 +10,4 @@ import { QueryClient, QueryClientConfig, dehydrate, hydrate } from "./client.mjs
 import { observer_d_exports } from "./observer.mjs";
 import { HasTypedError, PagingControls, PromiseControls, QueryControls, ReadValue, ThrowsOnError, UseQueryControls, UseQueryOptions, UseQueryThrowOptions, promiseControls, resultThenable, throwsOnError } from "./controls.mjs";
 import { binding_d_exports } from "./binding.mjs";
-export { type AnyQueryOptions, type DataOf, type DehydrateOptions, type DehydratedQuery, type DehydratedResult, type DehydratedState, type DehydratedStream, type ErrorOf, type HasTypedError, type HydrateOptions, type InfiniteData, type InfiniteQueryOptions, type InfiniteQueryTypes, type InputArgs, type InputOf, type IsPaged, type LoadOptions, type PageFunctionContext, type PageOf, type PagedQueryFactory, type PagingControls, type Pending, platform_d_exports as Platform, type PromiseControls, query_d_exports as Query, type QueryBehavior, binding_d_exports as QueryBinding, cache_d_exports as QueryCache, QueryClient, type QueryClientConfig, type QueryControls, type QueryFactory, type QueryFnResult, type QueryFunctionContext, type QueryHandle, type QueryHandleWithData, type QueryKey, type QueryMeta, observer_d_exports as QueryObserver, type QueryOptions, type QueryTypes, type ReadValue, RedactedError, type Register, type RetryPolicy, type ServicesOf, type Settled, type Thenable, type ThrowsOnError, type UseQueryControls, type UseQueryOptions, type UseQueryThrowOptions, allKeyed, canDehydrate, dehydrate, dehydrateQuery, fulfilled, hashKey, hydrate, infiniteQueryOptions, matchesKey, pending, promiseControls, queryOptions, resultThenable, throwsOnError };
+export { type AnyQueryOptions, type DataOf, type DehydrateOptions, type DehydratedQuery, type DehydratedResult, type DehydratedState, type DehydratedStream, type ErrorOf, type HasTypedError, type HydrateOptions, type InfiniteData, type InfiniteQueryOptions, type InfiniteQueryTypes, type InputArgs, type InputOf, type IsPaged, type LoadOptions, type PageFunctionContext, type PageOf, type PagedQueryFactory, type PagingControls, type Pending, platform_d_exports as Platform, type PromiseControls, query_d_exports as Query, type QueryBehavior, binding_d_exports as QueryBinding, cache_d_exports as QueryCache, QueryClient, type QueryClientConfig, type QueryControls, type QueryFactory, type QueryFnResult, type QueryFunctionContext, type QueryHandle, type QueryHandleWithData, type QueryKey, type QueryMeta, observer_d_exports as QueryObserver, type QueryOptions, type QueryTypes, type ReadValue, RedactedError, type Register, type RetryPolicy, type ServicesOf, type Settled, type Thenable, type ThrowOnErrorOf, type ThrowsOnError, type UseQueryControls, type UseQueryOptions, type UseQueryThrowOptions, allKeyed, canDehydrate, dehydrate, dehydrateQuery, fulfilled, hashKey, hydrate, infiniteQueryOptions, matchesKey, pending, promiseControls, queryOptions, resultThenable, throwsOnError };

package/dist/options.d.mts

@@ -6,7 +6,8 @@ import { Effect, Schedule } from "effect";
  * `queryFn` its error and the services it needs, and the shape of its key.
  * Leave `error` out and it is `unknown` (promises reject with anything);
  * leave `services` out and it is `never`; leave `key` out and it is any
- * {@link QueryKey}.
+ * {@link QueryKey}. `throwOnError` is the query's `throwOnError` option;
+ * leave it out when the query doesn't set one.
  *
  * ```ts
  * type PostOptions = QueryOptions<{ data: Post }>;
@@ -17,10 +18,12 @@ export interface QueryTypes {
   readonly error?: unknown;
   readonly key?: QueryKey;
   readonly services?: unknown;
+  readonly throwOnError?: boolean;
 }
 /**
  * The types of a paged query: one page, the param that loads it, and as in
- * {@link QueryTypes}, an Effect `queryFn`'s error and services and the key.
+ * {@link QueryTypes}, an Effect `queryFn`'s error and services, the key and
+ * `throwOnError`.
  */
 export interface InfiniteQueryTypes {
   readonly error?: unknown;
@@ -28,6 +31,7 @@ export interface InfiniteQueryTypes {
   readonly page: unknown;
   readonly pageParam: unknown;
   readonly services?: unknown;
+  readonly throwOnError?: boolean;
 }
 /** `error` of a types bag, `unknown` when it has none. */
 type ErrorIn<TTypes> = TTypes extends {
@@ -41,52 +45,39 @@ type ServicesIn<TTypes> = TTypes extends {
 type KeyIn<TTypes> = TTypes extends {
   readonly key: infer TKey extends QueryKey;
 } ? TKey : QueryKey;
+/** `throwOnError` of a types bag, `undefined` when it has none. */
+type ThrowIn<TTypes> = TTypes extends {
+  readonly throwOnError: infer TThrow extends boolean;
+} ? TThrow : undefined;
+/** One object type for an intersection, so bags read as written. */
+type Flat<T> = { [K in keyof T]: T[K]; };
+type ErrorPart<TError> = unknown extends TError ? unknown : {
+  error: TError;
+};
+type ServicesPart<TServices> = [TServices] extends [never] ? unknown : {
+  services: TServices;
+};
+type ThrowPart<TThrow> = [TThrow] extends [boolean] ? {
+  throwOnError: TThrow;
+} : unknown;
 /**
  * The bag `queryOptions` returns. `error` is left out when the `queryFn`
  * doesn't name one (`unknown`: a promise or a plain value). `services` is
  * left out when the `queryFn` needs none (`never`). An Effect's error,
  * including `never` when it can't fail, stays. `key` is always there, so two
- * factories with different key shapes have different types.
+ * factories with different key shapes have different types. `throwOnError`
+ * is there when the options set it.
  */
-type QueryTypesOf<TData, TError, TServices, TKey> = unknown extends TError ? [TServices] extends [never] ? {
-  data: TData;
-  key: TKey;
-} : {
-  data: TData;
-  key: TKey;
-  services: TServices;
-} : [TServices] extends [never] ? {
+type QueryTypesOf<TData, TError, TServices, TKey, TThrow> = Flat<{
   data: TData;
-  error: TError;
   key: TKey;
-} : {
-  data: TData;
-  error: TError;
-  key: TKey;
-  services: TServices;
-};
+} & ErrorPart<TError> & ServicesPart<TServices> & ThrowPart<TThrow>>;
 /** As {@link QueryTypesOf}, for a paged query. */
-type InfiniteQueryTypesOf<TPage, TPageParam, TError, TServices, TKey> = unknown extends TError ? [TServices] extends [never] ? {
-  key: TKey;
-  page: TPage;
-  pageParam: TPageParam;
-} : {
+type InfiniteQueryTypesOf<TPage, TPageParam, TError, TServices, TKey, TThrow> = Flat<{
   key: TKey;
   page: TPage;
   pageParam: TPageParam;
-  services: TServices;
-} : [TServices] extends [never] ? {
-  error: TError;
-  key: TKey;
-  page: TPage;
-  pageParam: TPageParam;
-} : {
-  error: TError;
-  key: TKey;
-  page: TPage;
-  pageParam: TPageParam;
-  services: TServices;
-};
+} & ErrorPart<TError> & ServicesPart<TServices> & ThrowPart<TThrow>>;
 /**
  * What a `queryFn` may return: a value, a promise, or an `Effect`. An
  * Effect's error type becomes the query's (promises reject with `unknown`),
@@ -183,7 +174,17 @@ interface ServicesField<TServices> {
    */
   readonly [servicesType]?: () => TServices;
 }
-export interface QueryOptions<TTypes extends QueryTypes> extends QueryBehavior, ServicesField<ServicesIn<TTypes>> {
+interface ThrowOnErrorField<TThrow> {
+  /**
+   * How reads of this query settle on failure when they don't set
+   * `throwOnError` themselves: `true` rejects (to an error boundary),
+   * `false` settles with a `Result`. Omit it for the client's default.
+   * Only an Effect `queryFn`'s typed error reads as a `Result`; a promise
+   * `queryFn` always rejects.
+   */
+  readonly throwOnError?: TThrow;
+}
+export interface QueryOptions<TTypes extends QueryTypes> extends QueryBehavior, ServicesField<ServicesIn<TTypes>>, ThrowOnErrorField<ThrowIn<TTypes>> {
   readonly kind: "query";
   queryFn(context: QueryFunctionContext): QueryFnResult<TTypes>;
   readonly queryKey: KeyIn<TTypes>;
@@ -205,7 +206,7 @@ export interface InfiniteQueryOptions<TTypes extends InfiniteQueryTypes> extends
   data: TTypes["page"];
   error: ErrorIn<TTypes>;
   services: ServicesIn<TTypes>;
-}>>, QueryBehavior, ServicesField<ServicesIn<TTypes>> {
+}>>, QueryBehavior, ServicesField<ServicesIn<TTypes>>, ThrowOnErrorField<ThrowIn<TTypes>> {
   readonly initialPageParam: TTypes["pageParam"];
   readonly kind: "infinite";
   /** Keep at most this many pages; the far end is dropped when paging. */
@@ -221,11 +222,13 @@ export type AnyQueryOptions = QueryOptions<{
   data: unknown;
   error: unknown;
   services: unknown;
+  throwOnError: boolean;
 }> | InfiniteQueryOptions<{
   error: unknown;
   page: unknown;
   pageParam: unknown;
   services: unknown;
+  throwOnError: boolean;
 }>;
 /**
  * Typed options for a query factory:
@@ -248,28 +251,33 @@ export type AnyQueryOptions = QueryOptions<{
  * factories with the same input and data but different keys have different
  * types, and a handle of one doesn't type-check where the other's goes.
  *
+ * `throwOnError: true` or `false` is kept as a literal too, so reads that
+ * don't set their own follow it in their types.
+ *
  * The type parameters are only there for TypeScript to infer the types bag
- * from `queryFn` and `queryKey`; it can't infer a bag's members.
+ * from `queryFn`, `queryKey` and `throwOnError`; it can't infer a bag's
+ * members. Passing them explicitly, pass `TThrow` too when setting
+ * `throwOnError`.
  */
-export declare function queryOptions<TData, TError = unknown, TServices = never, const TKey extends QueryKey = QueryKey>(options: Omit<QueryOptions<{
+export declare function queryOptions<TData, TError = unknown, TServices = never, const TKey extends QueryKey = QueryKey, TThrow extends boolean | undefined = undefined>(options: Omit<QueryOptions<{
   data: TData;
   error: TError;
   key: TKey;
   services: TServices;
-}>, "kind">): QueryOptions<QueryTypesOf<TData, TError, TServices, TKey>>;
+}>, "kind" | "throwOnError"> & ThrowOnErrorField<TThrow>): QueryOptions<QueryTypesOf<TData, TError, TServices, TKey, TThrow>>;
 /**
  * Typed options for a paged query factory. The page type is inferred from
  * `queryFn`, as in {@link queryOptions}. So is an Effect `queryFn`'s error;
  * a promise or a plain value leaves `error` out. The key's literal type is
  * kept, as in {@link queryOptions}.
  */
-export declare function infiniteQueryOptions<TPage, TPageParam, TError = unknown, TServices = never, const TKey extends QueryKey = QueryKey>(options: Omit<InfiniteQueryOptions<{
+export declare function infiniteQueryOptions<TPage, TPageParam, TError = unknown, TServices = never, const TKey extends QueryKey = QueryKey, TThrow extends boolean | undefined = undefined>(options: Omit<InfiniteQueryOptions<{
   error: TError;
   key: TKey;
   page: TPage;
   pageParam: TPageParam;
   services: TServices;
-}>, "kind">): InfiniteQueryOptions<InfiniteQueryTypesOf<TPage, TPageParam, TError, TServices, TKey>>;
+}>, "kind" | "throwOnError"> & ThrowOnErrorField<TThrow>): InfiniteQueryOptions<InfiniteQueryTypesOf<TPage, TPageParam, TError, TServices, TKey, TThrow>>;
 interface FactoryResult {
   readonly kind: "infinite" | "query";
   readonly queryKey: QueryKey;
@@ -327,6 +335,11 @@ export type ErrorOf<TFactory extends QueryFactory> = ReturnType<TFactory> extend
  * values, and for a factory of no particular query.
  */
 export type ServicesOf<TFactory extends QueryFactory> = ReturnType<TFactory> extends InfiniteQueryOptions<infer TTypes> ? ServicesIn<TTypes> : ReturnType<TFactory> extends QueryOptions<infer TTypes> ? ServicesIn<TTypes> : never;
+/**
+ * The `throwOnError` a factory's options set, `undefined` when they set
+ * none (or for a factory of no particular query).
+ */
+export type ThrowOnErrorOf<TFactory extends QueryFactory> = ReturnType<TFactory> extends InfiniteQueryOptions<infer TTypes> ? ThrowIn<TTypes> : ReturnType<TFactory> extends QueryOptions<infer TTypes> ? ThrowIn<TTypes> : undefined;
 /** Page type of a paged factory. */
 export type PageOf<TFactory extends QueryFactory> = ReturnType<TFactory> extends InfiniteQueryOptions<infer TTypes> ? TTypes["page"] : never;
 /**

package/dist/options.mjs

@@ -20,8 +20,13 @@
 * factories with the same input and data but different keys have different
 * types, and a handle of one doesn't type-check where the other's goes.
 *
+* `throwOnError: true` or `false` is kept as a literal too, so reads that
+* don't set their own follow it in their types.
+*
 * The type parameters are only there for TypeScript to infer the types bag
-* from `queryFn` and `queryKey`; it can't infer a bag's members.
+* from `queryFn`, `queryKey` and `throwOnError`; it can't infer a bag's
+* members. Passing them explicitly, pass `TThrow` too when setting
+* `throwOnError`.
 */
 function queryOptions(options) {
 	return {

package/package.json

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