@raf-query/core 0.5.3 → 0.6.0

package/CHANGELOG.md

@@ -1,8 +1,26 @@
 # Changelog
 
+## [0.6.0](https://github.com/KATT/raf-query/compare/0.5.3...0.6.0) (2026-10-14)
+
+### ⚠ BREAKING CHANGES
+
+* **core:** LoadOptions takes no type argument, and QueryCache.LoadArgs is gone.
+
+* **testing:** render in an async act so suspended trees resume ([#78](https://github.com/KATT/raf-query/issues/78)) ([c706b9d](https://github.com/KATT/raf-query/commit/c706b9db0d3ba3ea2d5b3fd1e21dc8e1fe315b82))
+
+### Features
+
+* **core:** ssr: false runs a query in the browser only ([#77](https://github.com/KATT/raf-query/issues/77)) ([22c47bd](https://github.com/KATT/raf-query/commit/22c47bdad9da2e9e84728017db3dde636c5d4113))
+
+### Bug Fixes
+
+* **core:** infer generic factory makers passed inline to a verb ([#76](https://github.com/KATT/raf-query/issues/76)) ([f0616f7](https://github.com/KATT/raf-query/commit/f0616f7cd4288fb4a00e784f6d94dc3880d19a39))
+* **core:** keep data written while a page loads ([#75](https://github.com/KATT/raf-query/issues/75)) ([d1b8ae5](https://github.com/KATT/raf-query/commit/d1b8ae560540cea345dad1008f8b4d8a467f48aa))
+* **react:** let beforeLoad return handles in TanStack Start route context ([#74](https://github.com/KATT/raf-query/issues/74)) ([70c2121](https://github.com/KATT/raf-query/commit/70c2121a1926b4045049e6d9bfe56778262be42f))
+
 ## [0.5.3](https://github.com/KATT/raf-query/compare/0.5.2...0.5.3) (2026-10-14)
 
-* compare prefetch, ensure and fetch in the starting queries demo ([#73](https://github.com/KATT/raf-query/issues/73)) ([b26a65e](https://github.com/KATT/raf-query/commit/b26a65e3e003f18308ce456646eba1d3f50c1357))
+- compare prefetch, ensure and fetch in the starting queries demo ([#73](https://github.com/KATT/raf-query/issues/73)) ([b26a65e](https://github.com/KATT/raf-query/commit/b26a65e3e003f18308ce456646eba1d3f50c1357))
 
 ## [0.5.2](https://github.com/KATT/raf-query/compare/0.5.1...0.5.2) (2026-10-14)
 

package/dist/cache.d.mts

@@ -1,10 +1,10 @@
 import { QueryKey } from "./key.mjs";
-import { DataOf, EnsuredQueryHandle, ErrorOf, InputArgs, InputOf, LoadOptions, QueryBehavior, QueryFactory, QueryHandle, ServicesOf } from "./options.mjs";
+import { DataOf, EnsuredQueryHandle, ErrorOf, InputArgs, InputOf, LoadOptions, PagedQueryFactory, QueryBehavior, QueryFactory, QueryHandle, ServicesOf } from "./options.mjs";
 import { DehydrateOptions, DehydratedState, DehydratedStream, HydrateOptions } from "./hydration.mjs";
 import { CancelledError, Query, State, query_d_exports } from "./query.mjs";
 import { Context, Effect, Layer, Option, Scope, Stream } from "effect";
 declare namespace cache_d_exports {
-  export { Config, Event, Filter, LoadArgs, QueryCache, Target, TypeId, Updater, isQueryCache, layer, make };
+  export { Config, Event, Filter, QueryCache, Target, TypeId, Updater, isQueryCache, layer, make };
 }
 export declare const TypeId = "~@raf-query/core/QueryCache";
 export type TypeId = typeof TypeId;
@@ -46,8 +46,6 @@ export interface Filter {
   readonly predicate?: (query: Query) => boolean;
   readonly queryKey?: QueryKey;
 }
-/** `ensure` / `fetch` arguments: the input, then load options for paged factories. */
-export type LoadArgs<TFactory extends QueryFactory> = InputArgs<TFactory> | [input: InputOf<TFactory>, options: LoadOptions<TFactory>];
 /** The entries `invalidate`, `reset` and `remove` act on: one factory call, or a filter. */
 export type Target<TFactory extends QueryFactory> = [factory: TFactory, ...args: InputArgs<TFactory>] | [filter: Filter];
 /**
@@ -55,6 +53,8 @@ export type Target<TFactory extends QueryFactory> = [factory: TFactory, ...args:
  * both with no data and with `undefined` data.
  */
 export type Updater<TData> = TData | ((previous: TData | undefined) => TData);
+type Ensured<TFactory extends QueryFactory> = Effect.Effect<EnsuredQueryHandle<TFactory>, ErrorOf<TFactory> | CancelledError, ServicesOf<TFactory>>;
+type Fetched<TFactory extends QueryFactory> = Effect.Effect<DataOf<TFactory>, ErrorOf<TFactory> | CancelledError, ServicesOf<TFactory>>;
 export interface QueryCache {
   /** Every entry. */
   readonly all: Effect.Effect<ReadonlyArray<Query>>;
@@ -75,7 +75,9 @@ export interface QueryCache {
    * browser. The handle is marked `ensured`, so `useQuery` returns its data
    * directly.
    */
-  ensure<TFactory extends QueryFactory>(factory: TFactory, ...args: LoadArgs<TFactory>): Effect.Effect<EnsuredQueryHandle<TFactory>, ErrorOf<TFactory> | CancelledError, ServicesOf<TFactory>>;
+  ensure<TFactory extends QueryFactory>(factory: TFactory, ...args: InputArgs<TFactory>): Ensured<TFactory>;
+  /** {@link ensure}, loading `options.pages` pages of a paged query. */
+  ensure<TFactory extends PagedQueryFactory>(factory: TFactory, input: InputOf<TFactory>, options: LoadOptions): Ensured<TFactory>;
   /** Cache events from the moment the stream starts. */
   readonly events: Stream.Stream<Event>;
   /**
@@ -83,7 +85,9 @@ export interface QueryCache {
    * stale data (on the server, only invalidated data), so the data is fresh.
    * Fails if that request fails.
    */
-  fetch<TFactory extends QueryFactory>(factory: TFactory, ...args: LoadArgs<TFactory>): Effect.Effect<DataOf<TFactory>, ErrorOf<TFactory> | CancelledError, ServicesOf<TFactory>>;
+  fetch<TFactory extends QueryFactory>(factory: TFactory, ...args: InputArgs<TFactory>): Fetched<TFactory>;
+  /** {@link fetch}, loading `options.pages` pages of a paged query. */
+  fetch<TFactory extends PagedQueryFactory>(factory: TFactory, input: InputOf<TFactory>, options: LoadOptions): Fetched<TFactory>;
   /**
    * Cached data for a factory call. `Some(undefined)` when the data itself
    * is `undefined`.

package/dist/cache.mjs

@@ -1,8 +1,8 @@
 import { __exportAll } from "./_virtual/_rolldown/runtime.mjs";
 import { Platform } from "./platform.mjs";
 import { unsafeCast } from "./cast.mjs";
-import { listen } from "./listen.mjs";
 import { hashKey, matchesKey } from "./key.mjs";
+import { listen } from "./listen.mjs";
 import { changes, emit, fetch, invalidate, isObserved, make as make$1, needsRefetch, onPlatformEvent, provide, remove, reset, revalidate, setData, setOptions, start } from "./entry.mjs";
 import { dehydrateEntries, dehydrateStream, hydrateEntries } from "./hydration.mjs";
 import { optionsFor } from "./options.mjs";
@@ -135,12 +135,12 @@ const make = /*#__PURE__*/ Effect.fnUntraced(function* (config = {}) {
 		}),
 		dehydrate: (options = {}) => Effect.sync(() => dehydrateEntries(state.entries.values(), options)),
 		dehydrateStream: (options = {}) => dehydrateStream(() => state.entries.values(), subscribeUnsafe, options),
-		ensure: (factory, ...args) => Effect.flatMap(buildFor(factory, args[0]), (entry) => load(entry, args[1]?.pages, false).pipe(Effect.as({
+		ensure: (factory, input, options) => Effect.flatMap(buildFor(factory, input), (entry) => load(entry, options?.pages, false).pipe(Effect.as({
 			...handleOf(entry),
 			ensured: true
 		}))),
 		events: listen(subscribeUnsafe),
-		fetch: (factory, ...args) => Effect.flatMap(buildFor(factory, args[0]), (entry) => load(entry, args[1]?.pages, true)),
+		fetch: (factory, input, options) => Effect.flatMap(buildFor(factory, input), (entry) => load(entry, options?.pages, true)),
 		getData: (factory, ...args) => Effect.sync(() => {
 			const options = optionsFor(factory, args[0]);
 			const entry = state.entries.get(hashKey(options.queryKey));

package/dist/entry.d.mts

@@ -6,7 +6,7 @@ import { Pending, Thenable } from "./thenable.mjs";
 import { FetchRequest, Query, State, SubscribeOptions } from "./query.mjs";
 import { Cause, Clock, Context, Deferred, Effect, Scope, Stream } from "effect";
 declare namespace entry_d_exports {
-  export { CacheState, CancelledError, Entry, TypeId, changes, emit, entryOf, fetch, hasNextPageUnsafe, hasPreviousPageUnsafe, invalidate, isObserved, isQuery, isStaleUnsafe, make, metaOf, needsRefetch, now, onPlatformEvent, provide, readUnsafe, remove, reset, resume, revalidate, setData, setOptions, start, subscribeUnsafe };
+  export { BrowserOnlyError, CacheState, CancelledError, Entry, TypeId, changes, emit, entryOf, fetch, hasNextPageUnsafe, hasPreviousPageUnsafe, invalidate, isBrowserOnly, isObserved, isQuery, isStaleUnsafe, make, metaOf, needsRefetch, now, 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,6 +19,18 @@ 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";
+} & 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.
+ */
+export declare class BrowserOnlyError extends BrowserOnlyError_base<{
+  readonly hash: string;
+}> {
+  get message(): string;
+}
 /**
  * The state a cache shares with its entries. Entries are created
  * synchronously (a render reads one), so they fork their fibers with the
@@ -89,6 +101,8 @@ export declare function make(cache: CacheState, key: QueryKey, hash: string): En
 export declare function now(entry: Entry): number;
 /** 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;
 /** 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

@@ -1,11 +1,11 @@
 import { whenOnline } from "./platform.mjs";
 import { unsafeCast } from "./cast.mjs";
+import { replaceEqualDeep } from "./share.mjs";
 import { fetchPages, isInfiniteData, nextPageParam, previousPageParam } from "./infinite.mjs";
 import { listen } from "./listen.mjs";
 import { scheduleNotify } from "./notify.mjs";
 import { fromQueryFn, requestServices, runRequest } from "./request.mjs";
 import { retrySchedule } from "./retry.mjs";
-import { replaceEqualDeep } from "./share.mjs";
 import { fulfilled, pending } from "./thenable.mjs";
 import { Cause, Data, Deferred, Effect, Exit, FiberMap, Pipeable, Predicate, Schedule, Scope } from "effect";
 //#region src/entry.ts
@@ -17,6 +17,15 @@ const TypeId = "~@raf-query/core/Query";
 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.
+*/
+var BrowserOnlyError = class extends Data.TaggedError("BrowserOnlyError") {
+	get message() {
+		return `Query ${this.hash} runs in the browser only (ssr: false)`;
+	}
+};
 const Proto = {
 	...Pipeable.Prototype,
 	[TypeId]: {
@@ -86,10 +95,11 @@ function make(cache, key, hash) {
 		},
 		tasks: makeTasks(cache, scope)
 	});
+	const command = (request) => Effect.suspend(() => isBrowserOnly(entry) ? Effect.void : Effect.ignore(fetch(entry, request)));
 	const commands = {
-		fetchNextPage: Effect.ignore(fetch(entry, { direction: "forward" })),
-		fetchPreviousPage: Effect.ignore(fetch(entry, { direction: "backward" })),
-		refetch: Effect.ignore(fetch(entry))
+		fetchNextPage: command({ direction: "forward" }),
+		fetchPreviousPage: command({ direction: "backward" }),
+		refetch: command()
 	};
 	Object.assign(entry, { commands });
 	scheduleGc(entry);
@@ -105,6 +115,10 @@ 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;
+}
 /** Until a factory call attaches options, `meta` comes from hydration. */
 function metaOf(entry) {
 	return entry.options ? behavior(entry, "meta") : entry.hydratedMeta ?? entry.cache.defaults.meta;
@@ -211,7 +225,7 @@ function fetch(entry, request = {}) {
 function invalidate(entry) {
 	return Effect.suspend(() => {
 		set(entry, { isInvalidated: true });
-		if (!isObserved(entry) || !entry.options) return Effect.void;
+		if (!isObserved(entry) || !entry.options || isBrowserOnly(entry)) return Effect.void;
 		return Effect.ignore(begin(entry, { restart: true }));
 	});
 }
@@ -230,7 +244,7 @@ function reset(entry) {
 			status: "pending",
 			updatedAt: 0
 		});
-		if (!entry.options || !isObserved(entry) && !entry.inFlight) return Effect.void;
+		if (!entry.options || isBrowserOnly(entry) || !isObserved(entry) && !entry.inFlight) return Effect.void;
 		return Effect.ignore(begin(entry, { restart: true }));
 	});
 }
@@ -277,6 +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);
+		return Effect.die(error);
+	}
 	const options = entry.options;
 	const inFlight = entry.inFlight;
 	if (inFlight && !(request.restart && options)) return Deferred.await(inFlight);
@@ -432,8 +453,8 @@ function requestEffect(entry, options, request) {
 			return readSignal();
 		}
 	}));
-	const current = isInfiniteData(entry.state.data) ? entry.state.data : void 0;
-	return fetchPages(options, current, request, (pageParam, direction) => attempt(entry, (readSignal) => options.queryFn({
+	const pagesOf = () => isInfiniteData(entry.state.data) ? entry.state.data : void 0;
+	return fetchPages(options, pagesOf(), request, (pageParam, direction) => attempt(entry, (readSignal) => options.queryFn({
 		direction,
 		meta,
 		pageParam,
@@ -441,7 +462,7 @@ function requestEffect(entry, options, request) {
 		get signal() {
 			return readSignal();
 		}
-	})));
+	})), pagesOf);
 }
 /**
 * One `queryFn` call, retried per the query's policy. Every failure counts.
@@ -499,4 +520,4 @@ function scheduleStale(entry) {
 	entry.tasks.fork("stale", Effect.sleep(Math.max(remaining, 0) + 1).pipe(Effect.andThen(Effect.sync(() => set(entry, {})))));
 }
 //#endregion
-export { CancelledError, TypeId, changes, emit, entryOf, fetch, hasNextPageUnsafe, hasPreviousPageUnsafe, invalidate, isObserved, isQuery, isStaleUnsafe, make, metaOf, needsRefetch, now, onPlatformEvent, provide, readUnsafe, remove, reset, resume, revalidate, setData, setOptions, start, subscribeUnsafe };
+export { BrowserOnlyError, CancelledError, TypeId, changes, emit, entryOf, fetch, hasNextPageUnsafe, hasPreviousPageUnsafe, invalidate, isBrowserOnly, isObserved, isQuery, isStaleUnsafe, make, metaOf, needsRefetch, now, onPlatformEvent, provide, readUnsafe, remove, reset, resume, revalidate, setData, setOptions, start, subscribeUnsafe };

package/dist/hydration.mjs

@@ -1,4 +1,4 @@
-import { resume, revalidate, setData } from "./entry.mjs";
+import { entryOf, isBrowserOnly, resume, revalidate, setData } from "./entry.mjs";
 import { getUnsafe, metaUnsafe } from "./query.mjs";
 import { Data, Effect, Queue, Stream } from "effect";
 //#region src/hydration.ts
@@ -53,7 +53,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) && filter(query)) {
+	for (const query of queries) if (!sent?.has(query.hash) && !isBrowserOnly(entryOf(query)) && filter(query)) {
 		sent?.add(query.hash);
 		dehydrated.push(dehydrateUnsafe(query, options));
 	}

package/dist/index.d.mts

@@ -1,9 +1,9 @@
 import { platform_d_exports } from "./platform.mjs";
 import { QueryKey, hashKey, matchesKey } from "./key.mjs";
-import { AnyQueryOptions, DataOf, EnsuredQueryHandle, ErrorOf, InfiniteData, InfiniteQueryOptions, InfiniteQueryTypes, InputArgs, InputOf, IsPaged, LoadOptions, PageFunctionContext, PageOf, QueryBehavior, QueryFactory, QueryFnResult, QueryFunctionContext, QueryHandle, QueryMeta, QueryOptions, QueryTypes, Register, RetryPolicy, ServicesOf, infiniteQueryOptions, queryOptions } from "./options.mjs";
+import { AnyQueryOptions, DataOf, EnsuredQueryHandle, ErrorOf, InfiniteData, InfiniteQueryOptions, InfiniteQueryTypes, InputArgs, InputOf, IsPaged, LoadOptions, PageFunctionContext, PageOf, PagedQueryFactory, QueryBehavior, QueryFactory, QueryFnResult, QueryFunctionContext, QueryHandle, QueryMeta, QueryOptions, QueryTypes, Register, RetryPolicy, ServicesOf, infiniteQueryOptions, queryOptions } from "./options.mjs";
 import { DehydrateOptions, DehydratedQuery, DehydratedResult, DehydratedState, DehydratedStream, HydrateOptions, RedactedError, canDehydrate, dehydrateQuery } from "./hydration.mjs";
 import { cache_d_exports } from "./cache.mjs";
 import { Thenable } from "./thenable.mjs";
 import { query_d_exports } from "./query.mjs";
 import { observer_d_exports } from "./observer.mjs";
-export { type AnyQueryOptions, type DataOf, type DehydrateOptions, type DehydratedQuery, type DehydratedResult, type DehydratedState, type DehydratedStream, type EnsuredQueryHandle, type ErrorOf, type HydrateOptions, type InfiniteData, type InfiniteQueryOptions, type InfiniteQueryTypes, type InputArgs, type InputOf, type IsPaged, type LoadOptions, type PageFunctionContext, type PageOf, platform_d_exports as Platform, query_d_exports as Query, type QueryBehavior, cache_d_exports as QueryCache, type QueryFactory, type QueryFnResult, type QueryFunctionContext, type QueryHandle, type QueryKey, type QueryMeta, observer_d_exports as QueryObserver, type QueryOptions, type QueryTypes, RedactedError, type Register, type RetryPolicy, type ServicesOf, type Thenable, canDehydrate, dehydrateQuery, hashKey, infiniteQueryOptions, matchesKey, queryOptions };
+export { type AnyQueryOptions, type DataOf, type DehydrateOptions, type DehydratedQuery, type DehydratedResult, type DehydratedState, type DehydratedStream, type EnsuredQueryHandle, type ErrorOf, type HydrateOptions, type InfiniteData, type InfiniteQueryOptions, type InfiniteQueryTypes, type InputArgs, type InputOf, type IsPaged, type LoadOptions, type PageFunctionContext, type PageOf, type PagedQueryFactory, platform_d_exports as Platform, query_d_exports as Query, type QueryBehavior, cache_d_exports as QueryCache, type QueryFactory, type QueryFnResult, type QueryFunctionContext, type QueryHandle, type QueryKey, type QueryMeta, observer_d_exports as QueryObserver, type QueryOptions, type QueryTypes, RedactedError, type Register, type RetryPolicy, type ServicesOf, type Thenable, canDehydrate, dehydrateQuery, hashKey, infiniteQueryOptions, matchesKey, queryOptions };

package/dist/infinite.mjs

@@ -1,3 +1,4 @@
+import { replaceEqualDeep } from "./share.mjs";
 import { Effect, Predicate } from "effect";
 //#region src/infinite.ts
 function isInfiniteData(data) {
@@ -27,16 +28,28 @@ function addPage(data, page, pageParam, direction, maxPages) {
 		pages: pages.slice(0, maxPages)
 	};
 }
+function edgeParam(data, direction) {
+	return direction === "forward" ? data.pageParams.at(-1) : data.pageParams[0];
+}
 /**
 * A paged query's request. With a `direction`, adds one page at that end of
-* `current`. Otherwise loads from the first page param again: as many pages
-* as `current` has, or `pages` if that's more, stopping at the last page.
+* the entry's data, read again with `latest` once the page loads, so data
+* written meanwhile (`setData`, a live subscription) stays. If that data no
+* longer ends at the page param the request started from, the write
+* replaced the list, and the page is dropped. Without a `direction`, loads
+* from the first page param again: as many pages as `current` has, or
+* `pages` if that's more, stopping at the last page.
 */
-const fetchPages = /*#__PURE__*/ Effect.fnUntraced(function* (options, current, request, fetchPage) {
-	if (request.direction && current) {
-		const pageParam = request.direction === "forward" ? nextPageParam(options, current) : previousPageParam(options, current);
+const fetchPages = /*#__PURE__*/ Effect.fnUntraced(function* (options, current, request, fetchPage, latest) {
+	const direction = request.direction;
+	if (direction && current) {
+		const pageParam = direction === "forward" ? nextPageParam(options, current) : previousPageParam(options, current);
 		if (pageParam == null) return current;
-		return addPage(current, yield* fetchPage(pageParam, request.direction), pageParam, request.direction, options.maxPages);
+		const page = yield* fetchPage(pageParam, direction);
+		const now = latest() ?? current;
+		const startedFrom = edgeParam(current, direction);
+		if (replaceEqualDeep(startedFrom, edgeParam(now, direction)) !== startedFrom) return now;
+		return addPage(now, page, pageParam, direction, options.maxPages);
 	}
 	const count = Math.max(request.pages ?? 1, current?.pages.length ?? 0);
 	let data = {

package/dist/options.d.mts

@@ -97,6 +97,15 @@ 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;
   /**
@@ -215,7 +224,22 @@ interface FactoryResult {
  * TypeScript infers an inline factory's `queryOptions` type arguments from
  * it, and an `unknown` there would infer `unknown` services.
  */
-export type QueryFactory<TServices = unknown> = (input: never) => unknown extends TServices ? FactoryResult : FactoryResult & ServicesField<TServices>;
+export type QueryFactory<TServices = unknown> = FactorySignature<unknown extends TServices ? FactoryResult : FactoryResult & ServicesField<TServices>>["call"];
+/** A {@link QueryFactory} returning `infiniteQueryOptions(...)`. */
+export type PagedQueryFactory<TServices = unknown> = FactorySignature<unknown extends TServices ? PagedFactoryResult : PagedFactoryResult & ServicesField<TServices>>["call"];
+interface PagedFactoryResult extends FactoryResult {
+  readonly kind: "infinite";
+}
+/**
+ * A method, so its `input` is checked bivariantly: a factory of any input
+ * type is assignable. A verb's factory parameter is contextually typed by
+ * this, and a generic factory maker called inline
+ * (`qc.ensure(makeFactory(x), input)`) infers its own type parameters
+ * against it. An `input: never` there would infer `never` for them.
+ */
+interface FactorySignature<TResult> {
+  call(input: unknown): TResult;
+}
 /** The factory's input type; `undefined` for factories without one. */
 export type InputOf<TFactory extends QueryFactory> = Parameters<TFactory> extends [] ? undefined : Parameters<TFactory>[0];
 /** Arguments after the factory: the input, optional when the factory's is. */
@@ -245,11 +269,15 @@ export type ErrorOf<TFactory extends QueryFactory> = ReturnType<TFactory> extend
 export type ServicesOf<TFactory extends QueryFactory> = ReturnType<TFactory> extends InfiniteQueryOptions<infer TTypes> ? ServicesIn<TTypes> : ReturnType<TFactory> extends QueryOptions<infer TTypes> ? ServicesIn<TTypes> : never;
 /** Page type of a paged factory. */
 export type PageOf<TFactory extends QueryFactory> = ReturnType<TFactory> extends InfiniteQueryOptions<infer TTypes> ? TTypes["page"] : never;
-/** `ensure` / `fetch` options. Only paged factories accept `pages`. */
-export type LoadOptions<TFactory extends QueryFactory> = IsPaged<TFactory> extends true ? {
+/**
+ * `ensure` / `fetch` options, for {@link PagedQueryFactory paged factories}
+ * only. Not generic: an options type that depends on the factory's type stops
+ * a generic factory maker called inline from inferring.
+ */
+export interface LoadOptions {
   /** Load this many pages up front (default 1). */
   readonly pages?: number;
-} : never;
+}
 declare const factoryType: unique symbol;
 interface HandleFields<TFactory extends QueryFactory> {
   /** Type-only: ties the handle to its factory. Never present at runtime. */

package/dist/query.d.mts

@@ -1,11 +1,11 @@
 import { QueryKey } from "./key.mjs";
 import { AnyQueryOptions, DataOf, ErrorOf, QueryFactory, QueryHandle, QueryMeta, ServicesOf } from "./options.mjs";
 import { Thenable } from "./thenable.mjs";
-import { CancelledError as CancelledError$1, TypeId as TypeId$1, entry_d_exports } from "./entry.mjs";
+import { BrowserOnlyError as BrowserOnlyError$1, CancelledError as CancelledError$1, TypeId as TypeId$1, entry_d_exports } from "./entry.mjs";
 import { Direction } from "./infinite.mjs";
 import { Effect, Pipeable, Stream } from "effect";
 declare namespace query_d_exports {
-  export { CancelledError, FetchRequest, Query, State, SubscribeOptions, TypeId, changes, fetch, fetchNextPage, fetchPreviousPage, get, getUnsafe, hasNextPageUnsafe, hasPreviousPageUnsafe, invalidate, isQuery, isStaleUnsafe, metaUnsafe, observerCountUnsafe, readUnsafe, refetch, reset, revalidateUnsafe, subscribeUnsafe };
+  export { BrowserOnlyError, CancelledError, FetchRequest, Query, State, SubscribeOptions, TypeId, changes, fetch, fetchNextPage, fetchPreviousPage, get, getUnsafe, hasNextPageUnsafe, hasPreviousPageUnsafe, invalidate, isQuery, isStaleUnsafe, metaUnsafe, observerCountUnsafe, readUnsafe, refetch, reset, revalidateUnsafe, subscribeUnsafe };
 }
 export declare const TypeId: typeof TypeId$1;
 export type TypeId = typeof TypeId;
@@ -67,6 +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 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,6 +1,6 @@
 import { __exportAll } from "./_virtual/_rolldown/runtime.mjs";
 import { unsafeCast } from "./cast.mjs";
-import { 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 { 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 { Effect } from "effect";
 import { dual } from "effect/Function";
 //#region src/query.ts
@@ -13,6 +13,7 @@ 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,
 	TypeId: () => TypeId,
 	changes: () => changes,
@@ -36,6 +37,7 @@ var query_exports = /* @__PURE__ */ __exportAll({
 });
 const TypeId = TypeId$1;
 const CancelledError = CancelledError$1;
+const BrowserOnlyError = BrowserOnlyError$1;
 const isQuery = isQuery$1;
 function typed(effect) {
 	return unsafeCast(effect);
@@ -133,4 +135,4 @@ function observerCountUnsafe(self) {
 	return entryOf(self).listeners.size;
 }
 //#endregion
-export { CancelledError, TypeId, changes, fetch, fetchNextPage, fetchPreviousPage, get, getUnsafe, hasNextPageUnsafe, hasPreviousPageUnsafe, invalidate, isQuery, isStaleUnsafe, metaUnsafe, observerCountUnsafe, query_exports, readUnsafe, refetch, reset, revalidateUnsafe, subscribeUnsafe };
+export { BrowserOnlyError, CancelledError, TypeId, changes, fetch, fetchNextPage, fetchPreviousPage, get, getUnsafe, hasNextPageUnsafe, hasPreviousPageUnsafe, invalidate, isQuery, isStaleUnsafe, metaUnsafe, observerCountUnsafe, query_exports, readUnsafe, refetch, reset, revalidateUnsafe, subscribeUnsafe };

package/package.json

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