@raf-query/core 0.10.4 → 0.11.1

package/CHANGELOG.md

@@ -1,11 +1,27 @@
 # 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))
+
+### 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))
+
 ## [0.10.4](https://github.com/KATT/raf-query/compare/0.10.3...0.10.4) (2026-10-16)
 
 ### Bug Fixes
 
-* **core:** keep pages written during a paged refetch ([#215](https://github.com/KATT/raf-query/issues/215)) ([b6a5946](https://github.com/KATT/raf-query/commit/b6a5946e806e12e9b7df40e80ef0e532c0871b25)), references [#75](https://github.com/KATT/raf-query/issues/75)
-* **react:** read promise queryFns as plain data on a client with a layer (1/2) ([#205](https://github.com/KATT/raf-query/issues/205)) ([a9b156e](https://github.com/KATT/raf-query/commit/a9b156edfa18b1e41e9ea929afc412252a61b83c))
+- **core:** keep pages written during a paged refetch ([#215](https://github.com/KATT/raf-query/issues/215)) ([b6a5946](https://github.com/KATT/raf-query/commit/b6a5946e806e12e9b7df40e80ef0e532c0871b25)), references [#75](https://github.com/KATT/raf-query/issues/75)
+- **react:** read promise queryFns as plain data on a client with a layer (1/2) ([#205](https://github.com/KATT/raf-query/issues/205)) ([a9b156e](https://github.com/KATT/raf-query/commit/a9b156edfa18b1e41e9ea929afc412252a61b83c))
 
 ## [0.10.3](https://github.com/KATT/raf-query/compare/0.10.2...0.10.3) (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/entry.d.mts

@@ -6,7 +6,7 @@ import { FetchRequest, Query, State, SubscribeOptions } from "./query.mjs";
 import { Event } from "./cache.mjs";
 import { Cause, Clock, Context, Deferred, Effect, Scope, Stream } from "effect";
 declare namespace entry_d_exports {
-  export { BrowserOnlyError, CacheState, CancelledError, Entry, TypeId, changes, emit, entryOf, fetch, hasNextPageUnsafe, hasPreviousPageUnsafe, invalidate, isBrowserOnly, isObserved, isQuery, isStaleUnsafe, make, metaOf, needsRefetch, onPlatformEvent, provide, readUnsafe, remove, reset, resume, revalidate, setData, setOptions, start, subscribeUnsafe };
+  export { CacheState, CancelledError, DisabledError, Entry, TypeId, changes, emit, entryOf, fetch, hasNextPageUnsafe, hasPreviousPageUnsafe, invalidate, isDisabled, isObserved, isQuery, isStaleUnsafe, make, metaOf, needsRefetch, onPlatformEvent, provide, readUnsafe, remove, reset, resume, revalidate, setData, setOptions, start, subscribeUnsafe };
 }
 export declare const TypeId = "~@raf-query/core/Query";
 declare const CancelledError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => Cause.YieldableError & {
@@ -19,14 +19,14 @@ declare const CancelledError_base: new <A extends Record<string, any> = {}>(args
 export declare class CancelledError extends CancelledError_base {
   readonly message = "The query was cancelled";
 }
-declare const BrowserOnlyError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => Cause.YieldableError & {
-  readonly _tag: "BrowserOnlyError";
+declare const DisabledError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => Cause.YieldableError & {
+  readonly _tag: "DisabledError";
 } & Readonly<A>;
 /**
- * Why a query with `ssr: false` has no data on the server: its promise
- * there rejects with this, and `ensure` / `fetch` die with it.
+ * Why a query with `enabled: false` has no data: `ensure` / `fetch` die
+ * with it, and on a server its promise rejects with it.
  */
-export declare class BrowserOnlyError extends BrowserOnlyError_base<{
+export declare class DisabledError extends DisabledError_base<{
   readonly hash: string;
 }> {
   get message(): string;
@@ -106,8 +106,8 @@ export declare function emit(cache: CacheState, event: Event): void;
 export declare function make(cache: CacheState, key: QueryKey, hash: string): Entry;
 /** Readers are subscribed; `invalidate` and focus refetch only what is read. */
 export declare function isObserved(entry: Entry): boolean;
-/** A server cache's entry for an `ssr: false` query: it never runs here. */
-export declare function isBrowserOnly(entry: Entry): boolean;
+/** The entry's latest factory call returned `enabled: false`: it doesn't run. */
+export declare function isDisabled(entry: Entry): boolean;
 /** Until a factory call attaches options, `meta` comes from hydration. */
 export declare function metaOf(entry: Entry): QueryMeta | undefined;
 export declare function isStaleUnsafe(entry: Entry): boolean;

package/dist/entry.mjs

@@ -17,12 +17,12 @@ var CancelledError = class extends Data.TaggedError("CancelledError") {
 	message = "The query was cancelled";
 };
 /**
-* Why a query with `ssr: false` has no data on the server: its promise
-* there rejects with this, and `ensure` / `fetch` die with it.
+* Why a query with `enabled: false` has no data: `ensure` / `fetch` die
+* with it, and on a server its promise rejects with it.
 */
-var BrowserOnlyError = class extends Data.TaggedError("BrowserOnlyError") {
+var DisabledError = class extends Data.TaggedError("DisabledError") {
 	get message() {
-		return `Query ${this.hash} runs in the browser only (ssr: false)`;
+		return `Query ${this.hash} is disabled (enabled: false)`;
 	}
 };
 const Proto = {
@@ -95,7 +95,7 @@ function make(cache, key, hash) {
 		},
 		tasks: makeTasks(cache, scope)
 	});
-	const command = (request) => Effect.suspend(() => isBrowserOnly(entry) ? Effect.void : Effect.ignore(fetch(entry, request)));
+	const command = (request) => Effect.suspend(() => isDisabled(entry) ? Effect.void : Effect.ignore(fetch(entry, request)));
 	const commands = {
 		fetchNextPage: command({ direction: "forward" }),
 		fetchPreviousPage: command({ direction: "backward" }),
@@ -115,9 +115,9 @@ function isObserved(entry) {
 function behavior(entry, name) {
 	return entry.options?.[name] ?? entry.cache.defaults[name];
 }
-/** A server cache's entry for an `ssr: false` query: it never runs here. */
-function isBrowserOnly(entry) {
-	return entry.cache.isServer && behavior(entry, "ssr") === false;
+/** The entry's latest factory call returned `enabled: false`: it doesn't run. */
+function isDisabled(entry) {
+	return behavior(entry, "enabled") === false;
 }
 /** Until a factory call attaches options, `meta` comes from hydration. */
 function metaOf(entry) {
@@ -225,7 +225,7 @@ function fetch(entry, request = {}) {
 function invalidate(entry) {
 	return Effect.suspend(() => {
 		set(entry, { isInvalidated: true });
-		if (!isObserved(entry) || !entry.options || isBrowserOnly(entry)) return Effect.void;
+		if (!isObserved(entry) || !entry.options || isDisabled(entry)) return Effect.void;
 		return Effect.ignore(begin(entry, { restart: true }));
 	});
 }
@@ -244,7 +244,7 @@ function reset(entry) {
 			status: "pending",
 			updatedAt: 0
 		});
-		if (!entry.options || isBrowserOnly(entry) || !isObserved(entry) && !entry.inFlight) return Effect.void;
+		if (!entry.options || isDisabled(entry) || !isObserved(entry) && !entry.inFlight) return Effect.void;
 		return Effect.ignore(begin(entry, { restart: true }));
 	});
 }
@@ -291,11 +291,13 @@ function remove(entry) {
 */
 function begin(entry, request) {
 	if (Predicate.isTagged(entry.scope.state, "Closed")) return Effect.fail(new CancelledError());
-	if (isBrowserOnly(entry)) {
-		const error = new BrowserOnlyError({ hash: entry.hash });
-		const firstLoad = entry.pending;
-		entry.pending = void 0;
-		firstLoad?.reject(error);
+	if (isDisabled(entry)) {
+		const error = new DisabledError({ hash: entry.hash });
+		if (entry.cache.isServer) {
+			const firstLoad = entry.pending;
+			entry.pending = void 0;
+			firstLoad?.reject(error);
+		}
 		return Effect.die(error);
 	}
 	const options = entry.options;
@@ -332,7 +334,7 @@ function startRequest(entry, request, direction, updatedAt) {
 	entry.retriesStopped = false;
 	entry.signalRead = false;
 	entry.tasks.cancel("gc");
-	if (!entry.state.hasData && entry.state.status === "error") {
+	if (!entry.state.hasData && !entry.pending) {
 		entry.pending = pending();
 		set(entry, {
 			error: null,
@@ -521,4 +523,4 @@ function scheduleStale(entry) {
 	entry.tasks.fork("stale", Effect.sleep(Math.max(remaining, 0) + 1).pipe(Effect.andThen(Effect.sync(() => set(entry, {})))));
 }
 //#endregion
-export { BrowserOnlyError, CancelledError, TypeId, changes, emit, entryOf, fetch, hasNextPageUnsafe, hasPreviousPageUnsafe, invalidate, isBrowserOnly, isObserved, isQuery, isStaleUnsafe, make, metaOf, needsRefetch, onPlatformEvent, provide, readUnsafe, remove, reset, resume, revalidate, setData, setOptions, start, subscribeUnsafe };
+export { CancelledError, DisabledError, TypeId, changes, emit, entryOf, fetch, hasNextPageUnsafe, hasPreviousPageUnsafe, invalidate, isDisabled, isObserved, isQuery, isStaleUnsafe, make, metaOf, needsRefetch, onPlatformEvent, provide, readUnsafe, remove, reset, resume, revalidate, setData, setOptions, start, subscribeUnsafe };

package/dist/hydration.mjs

@@ -1,4 +1,4 @@
-import { entryOf, isBrowserOnly, resume, revalidate, setData } from "./entry.mjs";
+import { entryOf, isDisabled, resume, revalidate, setData } from "./entry.mjs";
 import { getUnsafe, metaUnsafe, returnsEffectUnsafe } from "./query.mjs";
 import { Data, Effect, Queue, Stream } from "effect";
 //#region src/hydration.ts
@@ -62,7 +62,7 @@ function dehydrateEntries(queries, options) {
 	const filter = options.filter ?? canDehydrate;
 	const sent = options.sent;
 	const dehydrated = [];
-	for (const query of queries) if (!sent?.has(query.hash) && !isBrowserOnly(entryOf(query)) && filter(query)) {
+	for (const query of queries) if (!sent?.has(query.hash) && !isDisabled(entryOf(query)) && filter(query)) {
 		sent?.add(query.hash);
 		dehydrated.push(dehydrateUnsafe(query, options));
 	}

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] ? {
-  data: TData;
-  error: TError;
-  key: TKey;
-} : {
+type QueryTypesOf<TData, TError, TServices, TKey, TThrow> = Flat<{
   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] ? {
+type InfiniteQueryTypesOf<TPage, TPageParam, TError, TServices, TKey, TThrow> = Flat<{
   key: TKey;
   page: TPage;
   pageParam: TPageParam;
-} : {
-  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`),
@@ -135,6 +126,20 @@ export interface PageFunctionContext<TPageParam> extends QueryFunctionContext {
 export type RetryPolicy = boolean | number | Schedule.Schedule<unknown, unknown> | ((failureCount: number, error: unknown) => boolean);
 /** Options every query accepts. `QueryCache` defaults fill in the rest. */
 export interface QueryBehavior {
+  /**
+   * `false` keeps the query from running. Default `true`. The factory
+   * decides per call, so `enabled: typeof window !== "undefined"` runs a
+   * query only in the browser, for data only a browser has (permissions,
+   * device APIs, `localStorage`).
+   *
+   * While disabled, readers see `isPending`, `ensure` and `fetch` fail with
+   * `Query.DisabledError`, and `invalidate`, `reset` and `refetch` do
+   * nothing. In the browser, its promise stays pending until a factory
+   * call returns `true` and runs it. A server cache never sends it, and its
+   * promise rejects with `Query.DisabledError`: under Suspense, React
+   * renders the fallback on the server and the component in the browser.
+   */
+  readonly enabled?: boolean;
   /** How long an unread entry stays cached, in ms. `Infinity` keeps it. */
   readonly gcTime?: number;
   /**
@@ -151,15 +156,6 @@ export interface QueryBehavior {
   readonly retry?: RetryPolicy;
   /** Delay before retry number `failureCount` (1-based), in ms. */
   readonly retryDelay?: number | ((failureCount: number, error: unknown) => number);
-  /**
-   * `false`: only the browser runs the query, for data only a browser has
-   * (permissions, device APIs). A server cache never starts it or sends it.
-   * Readers there see `isPending`, and a promise that rejects with
-   * `Query.BrowserOnlyError`: under Suspense, React renders the fallback on
-   * the server and the query in the browser. `ensure` and `fetch` on the
-   * server fail with that error. Default `true`.
-   */
-  readonly ssr?: boolean;
   /** How long data counts as fresh, in ms. Fresh data is never refetched. */
   readonly staleTime?: number;
   /**
@@ -178,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>;
@@ -200,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. */
@@ -216,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:
@@ -243,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;
@@ -322,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/dist/query.d.mts

@@ -2,10 +2,10 @@ import { QueryKey } from "./key.mjs";
 import { AnyQueryOptions, DataOf, ErrorOf, QueryFactory, QueryHandle, QueryMeta, ServicesOf } from "./options.mjs";
 import { Direction } from "./infinite.mjs";
 import { Thenable } from "./thenable.mjs";
-import { BrowserOnlyError as BrowserOnlyError$1, CancelledError as CancelledError$1, TypeId as TypeId$1, entry_d_exports } from "./entry.mjs";
+import { CancelledError as CancelledError$1, DisabledError as DisabledError$1, TypeId as TypeId$1, entry_d_exports } from "./entry.mjs";
 import { Effect, Pipeable, Stream } from "effect";
 declare namespace query_d_exports {
-  export { BrowserOnlyError, CancelledError, FetchRequest, Query, State, SubscribeOptions, TypeId, changes, fetch, fetchNextPage, fetchPreviousPage, get, getUnsafe, hasNextPageUnsafe, hasPreviousPageUnsafe, invalidate, isQuery, isStaleUnsafe, metaUnsafe, observerCountUnsafe, readUnsafe, refetch, reset, returnsEffectUnsafe, revalidateUnsafe, subscribeUnsafe };
+  export { CancelledError, DisabledError, FetchRequest, Query, State, SubscribeOptions, TypeId, changes, fetch, fetchNextPage, fetchPreviousPage, get, getUnsafe, hasNextPageUnsafe, hasPreviousPageUnsafe, invalidate, isQuery, isStaleUnsafe, metaUnsafe, observerCountUnsafe, readUnsafe, refetch, reset, returnsEffectUnsafe, revalidateUnsafe, subscribeUnsafe };
 }
 export declare const TypeId: typeof TypeId$1;
 export type TypeId = typeof TypeId;
@@ -67,8 +67,8 @@ export interface FetchRequest {
 }
 export declare const CancelledError: typeof CancelledError$1;
 export type CancelledError = CancelledError$1;
-export declare const BrowserOnlyError: typeof BrowserOnlyError$1;
-export type BrowserOnlyError = BrowserOnlyError$1;
+export declare const DisabledError: typeof DisabledError$1;
+export type DisabledError = DisabledError$1;
 export declare const isQuery: (value: unknown) => value is Query;
 /**
  * Start a request, or join the one in flight. Fails with the request's

package/dist/query.mjs

@@ -1,5 +1,5 @@
 import { __exportAll } from "./_virtual/_rolldown/runtime.mjs";
-import { BrowserOnlyError as BrowserOnlyError$1, CancelledError as CancelledError$1, TypeId as TypeId$1, changes as changes$1, entryOf, fetch as fetch$1, hasNextPageUnsafe as hasNextPageUnsafe$1, hasPreviousPageUnsafe as hasPreviousPageUnsafe$1, invalidate as invalidate$1, isQuery as isQuery$1, isStaleUnsafe as isStaleUnsafe$1, metaOf, provide, readUnsafe as readUnsafe$1, reset as reset$1, revalidate, subscribeUnsafe as subscribeUnsafe$1 } from "./entry.mjs";
+import { CancelledError as CancelledError$1, DisabledError as DisabledError$1, TypeId as TypeId$1, changes as changes$1, entryOf, fetch as fetch$1, hasNextPageUnsafe as hasNextPageUnsafe$1, hasPreviousPageUnsafe as hasPreviousPageUnsafe$1, invalidate as invalidate$1, isQuery as isQuery$1, isStaleUnsafe as isStaleUnsafe$1, metaOf, provide, readUnsafe as readUnsafe$1, reset as reset$1, revalidate, subscribeUnsafe as subscribeUnsafe$1 } from "./entry.mjs";
 import { Effect } from "effect";
 import { dual } from "effect/Function";
 //#region src/query.ts
@@ -12,8 +12,8 @@ import { dual } from "effect/Function";
 * synchronously, for renders and external stores that can't run an Effect.
 */
 var query_exports = /* @__PURE__ */ __exportAll({
-	BrowserOnlyError: () => BrowserOnlyError,
 	CancelledError: () => CancelledError,
+	DisabledError: () => DisabledError,
 	TypeId: () => TypeId,
 	changes: () => changes,
 	fetch: () => fetch,
@@ -37,7 +37,7 @@ var query_exports = /* @__PURE__ */ __exportAll({
 });
 const TypeId = TypeId$1;
 const CancelledError = CancelledError$1;
-const BrowserOnlyError = BrowserOnlyError$1;
+const DisabledError = DisabledError$1;
 const isQuery = isQuery$1;
 function typed(effect) {
 	return effect;
@@ -144,4 +144,4 @@ function observerCountUnsafe(self) {
 	return entryOf(self).listeners.size;
 }
 //#endregion
-export { BrowserOnlyError, CancelledError, TypeId, changes, fetch, fetchNextPage, fetchPreviousPage, get, getUnsafe, hasNextPageUnsafe, hasPreviousPageUnsafe, invalidate, isQuery, isStaleUnsafe, metaUnsafe, observerCountUnsafe, query_exports, readUnsafe, refetch, reset, returnsEffectUnsafe, revalidateUnsafe, subscribeUnsafe };
+export { CancelledError, DisabledError, TypeId, changes, fetch, fetchNextPage, fetchPreviousPage, get, getUnsafe, hasNextPageUnsafe, hasPreviousPageUnsafe, invalidate, isQuery, isStaleUnsafe, metaUnsafe, observerCountUnsafe, query_exports, readUnsafe, refetch, reset, returnsEffectUnsafe, revalidateUnsafe, subscribeUnsafe };

package/package.json

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