@raf-query/core 0.10.3 → 0.10.4

package/CHANGELOG.md

@@ -1,10 +1,17 @@
 # Changelog
 
+## [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

@@ -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;
   /**

package/dist/entry.mjs

@@ -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,
@@ -475,7 +476,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({

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 { 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);
@@ -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/query.d.mts

@@ -5,7 +5,7 @@ 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 { 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 { 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 declare const TypeId: typeof TypeId$1;
 export type TypeId = typeof TypeId;
@@ -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

@@ -31,6 +31,7 @@ var query_exports = /* @__PURE__ */ __exportAll({
 	readUnsafe: () => readUnsafe,
 	refetch: () => refetch,
 	reset: () => reset,
+	returnsEffectUnsafe: () => returnsEffectUnsafe,
 	revalidateUnsafe: () => revalidateUnsafe,
 	subscribeUnsafe: () => subscribeUnsafe
 });
@@ -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 { BrowserOnlyError, CancelledError, 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.10.4",
   "description": "Framework-agnostic core of raf-query, a render-as-you-fetch query library",
   "keywords": [
     "query",