@raf-query/core 0.10.3 → 0.11.0

package/CHANGELOG.md

@@ -1,10 +1,27 @@
 # Changelog
 
+## [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))
+
 ## [0.10.3](https://github.com/KATT/raf-query/compare/0.10.2...0.10.3) (2026-10-16)
 
 ### Features
 
-* **core:** add QueryBinding, a framework-free useQuery for bindings ([#197](https://github.com/KATT/raf-query/issues/197)) ([4865802](https://github.com/KATT/raf-query/commit/48658024f4d21d43ce8274de379a19c8898b6173)), references [#194](https://github.com/KATT/raf-query/issues/194)
+- **core:** add QueryBinding, a framework-free useQuery for bindings ([#197](https://github.com/KATT/raf-query/issues/197)) ([4865802](https://github.com/KATT/raf-query/commit/48658024f4d21d43ce8274de379a19c8898b6173)), references [#194](https://github.com/KATT/raf-query/issues/194)
 
 ## [0.10.2](https://github.com/KATT/raf-query/compare/0.10.1...0.10.2) (2026-10-16)
 

package/dist/client.d.mts

@@ -17,7 +17,8 @@ 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; this flag does not apply to them.
+   * Promise `queryFn`s always throw, whatever this flag says: reads tell
+   * them apart by what the `queryFn` returned ({@link Query.returnsEffectUnsafe}).
    */
   readonly throwOnError?: boolean;
 }

package/dist/controls.d.mts

@@ -1,6 +1,7 @@
 import { QueryKey } from "./key.mjs";
 import { DataOf, ErrorOf, InputOf, IsPaged, QueryFactory } 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";
 import { Result } from "effect";
 //#region src/controls.d.ts
@@ -65,6 +66,13 @@ export type HasTypedError<TFactory extends QueryFactory> = unknown extends Error
  * (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;
+/**
+ * {@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`.
+ */
+export declare function throwsOnError<TFactory extends QueryFactory>(query: Query<TFactory>, throwOnError: 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

@@ -1,4 +1,5 @@
 import { fulfilled, pending } from "./thenable.mjs";
+import { returnsEffectUnsafe } from "./query.mjs";
 import { Effect, Result } from "effect";
 //#region src/controls.ts
 /**
@@ -6,6 +7,15 @@ import { Effect, Result } from "effect";
 * observer's result with Promise commands, and the types every binding
 * shares. The React, Svelte and Vue packages build their reads on this.
 */
+/**
+* {@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`.
+*/
+function throwsOnError(query, throwOnError) {
+	return throwOnError || returnsEffectUnsafe(query) === false;
+}
 const commands = /* @__PURE__ */ new WeakMap();
 /** One stable Promise function per command Effect, so identities track the query's. */
 function commandFor(effect) {
@@ -56,4 +66,4 @@ function resultThenable(promise) {
 	return next;
 }
 //#endregion
-export { promiseControls, resultThenable };
+export { promiseControls, resultThenable, throwsOnError };

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;
@@ -79,6 +79,12 @@ export interface Entry extends Query {
   pending: Pending<unknown> | undefined;
   /** The last reader left during the request in flight: it retries no more. */
   retriesStopped: boolean;
+  /**
+   * The last `queryFn` call returned an Effect (`true`) or a promise or
+   * plain value (`false`), here or on the cache it was hydrated from.
+   * `undefined` until one has run.
+   */
+  returnsEffect: boolean | undefined;
   /** Open while the entry is cached; owns its fibers. */
   readonly scope: Scope.Closeable;
   /**
@@ -100,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 = {
@@ -76,6 +76,7 @@ function make(cache, key, hash) {
 		options: void 0,
 		pending: first,
 		retriesStopped: false,
+		returnsEffect: void 0,
 		scope,
 		services: cache.services,
 		signalRead: false,
@@ -94,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" }),
@@ -114,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) {
@@ -224,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 }));
 	});
 }
@@ -243,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 }));
 	});
 }
@@ -290,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;
@@ -331,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,
@@ -475,7 +478,8 @@ function attempt(entry, call) {
 			entry.signalRead = true;
 			return signal;
 		});
-		if (Effect.isEffect(result)) entry.signalRead = true;
+		entry.returnsEffect = Effect.isEffect(result);
+		if (entry.returnsEffect) entry.signalRead = true;
 		return result;
 	}).pipe(Effect.tapError(() => Effect.sync(() => set(entry, { failureCount: entry.state.failureCount + 1 }))));
 	const schedule = retrySchedule({
@@ -519,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.d.mts

@@ -18,6 +18,8 @@ export interface DehydratedResult {
  */
 export interface DehydratedQuery {
   readonly data?: unknown;
+  /** Whether the sender's `queryFn` returned an Effect, when it ran there. */
+  readonly effect?: boolean;
   readonly key: QueryKey;
   /** The query's `meta`, for receivers that haven't called its factory. */
   readonly meta?: QueryMeta;

package/dist/hydration.mjs

@@ -1,5 +1,5 @@
-import { entryOf, isBrowserOnly, resume, revalidate, setData } from "./entry.mjs";
-import { getUnsafe, metaUnsafe } from "./query.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
 /**
@@ -19,6 +19,15 @@ function canDehydrate(query) {
 	return state.hasData || state.isFetching;
 }
 function dehydrateUnsafe(query, options) {
+	const sent = dehydrateState(query, options);
+	const effect = returnsEffectUnsafe(query);
+	return effect === void 0 ? sent : {
+		...sent,
+		effect
+	};
+}
+/** {@link dehydrateUnsafe} without `effect`. */
+function dehydrateState(query, options) {
 	const state = getUnsafe(query);
 	const serialize = options.serializeData ?? identity;
 	const meta = metaUnsafe(query);
@@ -53,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));
 	}
@@ -123,6 +132,7 @@ function hydrateEntries(entryFor, state, options) {
 	for (const query of state.queries) {
 		const entry = entryFor(query.key);
 		if (!entry.options && query.meta !== void 0) entry.hydratedMeta = query.meta;
+		entry.returnsEffect ??= query.effect;
 		if (query.updatedAt > 0) takeNewer(entry, deserialize(query.data), query.updatedAt);
 		else if (query.promise) {
 			const result = Promise.resolve(query.promise).then((sent) => ({

package/dist/index.d.mts

@@ -8,6 +8,6 @@ import { DehydrateOptions, DehydratedQuery, DehydratedResult, DehydratedState, D
 import { cache_d_exports } from "./cache.mjs";
 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 } from "./controls.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 };
+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 };

package/dist/index.mjs

@@ -7,7 +7,7 @@ import { RedactedError, canDehydrate, dehydrateQuery } from "./hydration.mjs";
 import { infiniteQueryOptions, queryOptions } from "./options.mjs";
 import { cache_exports } from "./cache.mjs";
 import { QueryClient, dehydrate, hydrate } from "./client.mjs";
-import { promiseControls, resultThenable } from "./controls.mjs";
+import { promiseControls, resultThenable, throwsOnError } from "./controls.mjs";
 import { observer_exports } from "./observer.mjs";
 import { binding_exports } from "./binding.mjs";
-export { platform_exports as Platform, query_exports as Query, binding_exports as QueryBinding, cache_exports as QueryCache, QueryClient, observer_exports as QueryObserver, RedactedError, allKeyed, canDehydrate, dehydrate, dehydrateQuery, fulfilled, hashKey, hydrate, infiniteQueryOptions, matchesKey, pending, promiseControls, queryOptions, resultThenable };
+export { platform_exports as Platform, query_exports as Query, binding_exports as QueryBinding, cache_exports as QueryCache, QueryClient, observer_exports as QueryObserver, RedactedError, allKeyed, canDehydrate, dehydrate, dehydrateQuery, fulfilled, hashKey, hydrate, infiniteQueryOptions, matchesKey, pending, promiseControls, queryOptions, resultThenable, throwsOnError };

package/dist/infinite.mjs

@@ -1,5 +1,5 @@
 import { replaceEqualDeep } from "./share.mjs";
-import { Effect, Predicate } from "effect";
+import { Effect, Option, Predicate } from "effect";
 //#region src/infinite.ts
 function isInfiniteData(data) {
 	return Predicate.hasProperty(data, "pages") && Predicate.hasProperty(data, "pageParams") && Array.isArray(data.pages) && Array.isArray(data.pageParams);
@@ -31,6 +31,31 @@ function addPage(data, page, pageParam, direction, maxPages) {
 function edgeParam(data, direction) {
 	return direction === "forward" ? data.pageParams.at(-1) : data.pageParams[0];
 }
+/** The page `data` holds for `pageParam`, compared deeply. */
+function pageFor(data, pageParam) {
+	const index = data?.pageParams.findIndex((param) => replaceEqualDeep(param, pageParam) === param) ?? -1;
+	return index === -1 ? Option.none() : Option.some(data?.pages[index]);
+}
+/**
+* `data`, a full refetch's pages, with each page that `latest` replaced
+* after the refetch started reading it: that write is newer than the read.
+* A page written before its read started is read again, and the read wins.
+*/
+function keepWrites(data, readFrom, latest) {
+	let changed = false;
+	const pages = data.pages.map((page, index) => {
+		const pageParam = data.pageParams[index];
+		const read = readFrom.find((entry) => replaceEqualDeep(entry.pageParam, pageParam) === entry.pageParam);
+		const now = pageFor(latest, pageParam);
+		if (!read || Option.isNone(now) || Option.isSome(read.seen) && read.seen.value === now.value) return page;
+		changed = true;
+		return now.value;
+	});
+	return changed ? {
+		pageParams: data.pageParams,
+		pages
+	} : data;
+}
 /**
 * A paged query's request. With a `direction`, adds one page at that end of
 * the entry's data, read again with `latest` once the page loads, so data
@@ -38,7 +63,8 @@ function edgeParam(data, direction) {
 * 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.
+* `pages` if that's more, stopping at the last page. A page written while
+* the refetch was reading it, or after, stays as written ({@link keepWrites}).
 */
 const fetchPages = /*#__PURE__*/ Effect.fnUntraced(function* (options, current, request, fetchPage, latest) {
 	const direction = request.direction;
@@ -56,6 +82,7 @@ const fetchPages = /*#__PURE__*/ Effect.fnUntraced(function* (options, current,
 		pageParams: [],
 		pages: []
 	};
+	const readFrom = [];
 	let pageParam = current && current.pageParams.length > 0 ? current.pageParams[0] : options.initialPageParam;
 	for (let index = 0; index < count; index++) {
 		if (index > 0) {
@@ -63,10 +90,14 @@ const fetchPages = /*#__PURE__*/ Effect.fnUntraced(function* (options, current,
 			if (next == null) break;
 			pageParam = next;
 		}
+		readFrom.push({
+			pageParam,
+			seen: pageFor(latest(), pageParam)
+		});
 		const page = yield* fetchPage(pageParam, "forward");
 		data = addPage(data, page, pageParam, "forward", options.maxPages);
 	}
-	return data;
+	return keepWrites(data, readFrom, latest());
 });
 //#endregion
 export { fetchPages, isInfiniteData, nextPageParam, previousPageParam };

package/dist/options.d.mts

@@ -135,6 +135,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 +165,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;
   /**

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, 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
@@ -98,6 +98,13 @@ export declare function reset<TFactory extends QueryFactory>(self: Query<TFactor
  * with, before any), else the cache default's.
  */
 export declare function metaUnsafe<TFactory extends QueryFactory>(self: Query<TFactory>): QueryMeta | undefined;
+/**
+ * Whether the query's `queryFn` returns an Effect (`true`) or a promise or
+ * plain value (`false`), as of its last call, on this cache or the one its
+ * data was hydrated from. `undefined` until one has run. Bindings read typed
+ * errors as a `Result` only for Effects.
+ */
+export declare function returnsEffectUnsafe<TFactory extends QueryFactory>(self: Query<TFactory>): boolean | undefined;
 /** The entry's current state. */
 export declare function get<TFactory extends QueryFactory>(self: Query<TFactory>): Effect.Effect<State<DataOf<TFactory>>>;
 /** {@link get}, synchronously. */

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,
@@ -31,12 +31,13 @@ var query_exports = /* @__PURE__ */ __exportAll({
 	readUnsafe: () => readUnsafe,
 	refetch: () => refetch,
 	reset: () => reset,
+	returnsEffectUnsafe: () => returnsEffectUnsafe,
 	revalidateUnsafe: () => revalidateUnsafe,
 	subscribeUnsafe: () => subscribeUnsafe
 });
 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;
@@ -85,6 +86,15 @@ function reset(self) {
 function metaUnsafe(self) {
 	return metaOf(entryOf(self));
 }
+/**
+* Whether the query's `queryFn` returns an Effect (`true`) or a promise or
+* plain value (`false`), as of its last call, on this cache or the one its
+* data was hydrated from. `undefined` until one has run. Bindings read typed
+* errors as a `Result` only for Effects.
+*/
+function returnsEffectUnsafe(self) {
+	return entryOf(self).returnsEffect;
+}
 /** The entry's current state. */
 function get(self) {
 	return Effect.sync(() => getUnsafe(self));
@@ -134,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, 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.3",
+  "version": "0.11.0",
   "description": "Framework-agnostic core of raf-query, a render-as-you-fetch query library",
   "keywords": [
     "query",