@raf-query/core 0.10.1 → 0.10.2

package/CHANGELOG.md

@@ -1,14 +1,21 @@
 # Changelog
 
+## [0.10.2](https://github.com/KATT/raf-query/compare/0.10.1...0.10.2) (2026-10-16)
+
+### Features
+
+* **react:** re-render useQuery readers of the thenable's status when the first load settles (2/3) ([#198](https://github.com/KATT/raf-query/issues/198)) ([436d83c](https://github.com/KATT/raf-query/commit/436d83cfd6a3944265eb56d5597c322342c5a6c6))
+* **react:** type useQuery's promise as a Thenable (1/3) ([#200](https://github.com/KATT/raf-query/issues/200)) ([47e5309](https://github.com/KATT/raf-query/commit/47e530957565a2bd345642ae7a4be5d3c501ffb2))
+
 ## [0.10.1](https://github.com/KATT/raf-query/compare/0.10.0...0.10.1) (2026-10-16)
 
 ### Features
 
-* **core:** export QueryClient, dehydrate, hydrate, allKeyed and the useQuery controls from @raf-query/core ([#193](https://github.com/KATT/raf-query/issues/193)) ([54492ab](https://github.com/KATT/raf-query/commit/54492abbe2966a0645e8a4c77f9c5ab31d6e3a20)), references [#194](https://github.com/KATT/raf-query/issues/194)
+- **core:** export QueryClient, dehydrate, hydrate, allKeyed and the useQuery controls from @raf-query/core ([#193](https://github.com/KATT/raf-query/issues/193)) ([54492ab](https://github.com/KATT/raf-query/commit/54492abbe2966a0645e8a4c77f9c5ab31d6e3a20)), references [#194](https://github.com/KATT/raf-query/issues/194)
 
 ### Documentation
 
-* React Router client-only and server sections with one server client per request, Effect under Integrations, official docs links, and ensure waits like fetch in server-only code ([#192](https://github.com/KATT/raf-query/issues/192)) ([841ffcf](https://github.com/KATT/raf-query/commit/841ffcf4d0fa0a40dfc58dc65bfcfadca8948874)), references [#190](https://github.com/KATT/raf-query/issues/190)
+- React Router client-only and server sections with one server client per request, Effect under Integrations, official docs links, and ensure waits like fetch in server-only code ([#192](https://github.com/KATT/raf-query/issues/192)) ([841ffcf](https://github.com/KATT/raf-query/commit/841ffcf4d0fa0a40dfc58dc65bfcfadca8948874)), references [#190](https://github.com/KATT/raf-query/issues/190)
 
 ## [0.10.0](https://github.com/KATT/raf-query/compare/0.9.2...0.10.0) (2026-10-16)
 

package/dist/observer.d.mts

@@ -4,7 +4,7 @@ import { Thenable } from "./thenable.mjs";
 import { Query, query_d_exports } from "./query.mjs";
 import { Effect, Pipeable, Stream } from "effect";
 declare namespace observer_d_exports {
-  export { Options, QueryObserver, Result$1 as Result, ResultKey, TypeId, changes, get, getOptimisticResultUnsafe, getUnsafe, isQueryObserver, make, makeUnsafe, setOptionsUnsafe, subscribeUnsafe, trackProp, trackResult };
+  export { Options, QueryObserver, Result$1 as Result, ResultKey, TypeId, changes, get, getOptimisticResultUnsafe, getUnsafe, isQueryObserver, make, makeUnsafe, setOptionsUnsafe, subscribeUnsafe, trackProp, trackResult, trackThenable };
 }
 export declare const TypeId = "~@raf-query/core/QueryObserver";
 export type TypeId = typeof TypeId;
@@ -96,6 +96,14 @@ export declare function changes<TFactory extends QueryFactory>(self: QueryObserv
  * changes.
  */
 export declare function trackResult<TFactory extends QueryFactory, TResult extends Result$1<DataOf<TFactory>>>(self: QueryObserver<TFactory>, result: TResult): TResult;
+/**
+ * Wrap `promise`, the result's or one derived from it, so that reading its
+ * `status`, `value` or `reason` marks its settling as tracked. A first load
+ * settles its promise in place, without a new promise, so only readers of
+ * those fields need to hear about it. The mark is the wrapper's, shared by
+ * the observers that hand it out.
+ */
+export declare function trackThenable<TFactory extends QueryFactory, TThenable extends Thenable<unknown>>(self: QueryObserver<TFactory>, promise: TThenable): TThenable;
 /** Mark `name` as read, for bindings that track access themselves. */
 export declare function trackProp<TFactory extends QueryFactory>(self: QueryObserver<TFactory>, name: ResultKey): void;
 //#endregion

package/dist/observer.mjs

@@ -10,7 +10,8 @@ import { Effect, Exit, FiberHandle, Pipeable, Predicate, Scope } from "effect";
 * Query's `QueryObserver`: it derives the reader's result from the query's
 * state, keeps a previous query's data for `whilePending: "previous"`, runs
 * `refetchInterval`, and notifies its listeners only when a result property
-* they read changed (see {@link trackResult}). Bindings make one per hook.
+* they read changed (see {@link trackResult}), or a promise whose `status`
+* they read settled (see {@link trackThenable}). Bindings make one per hook.
 *
 * The `*Unsafe` functions read and update synchronously, for renders and
 * external stores. While it has listeners, the observer holds a `Scope` (a
@@ -30,7 +31,8 @@ var observer_exports = /* @__PURE__ */ __exportAll({
 	setOptionsUnsafe: () => setOptionsUnsafe,
 	subscribeUnsafe: () => subscribeUnsafe,
 	trackProp: () => trackProp,
-	trackResult: () => trackResult
+	trackResult: () => trackResult,
+	trackThenable: () => trackThenable
 });
 const TypeId = "~@raf-query/core/QueryObserver";
 const Proto = {
@@ -65,9 +67,16 @@ function implOf(self) {
 function isResultKey(name) {
 	return Predicate.isString(name) && Object.hasOwn(resultKeys, name);
 }
-function shallowEqual(a, b) {
-	for (const name of Object.keys(resultKeys)) if (isResultKey(name) && a[name] !== b[name]) return false;
-	return true;
+/** Whether `next.promise` has a different status than it had in the current result. */
+function settled(self, next) {
+	return self.currentStatus !== next.promise.status;
+}
+function anyChanged(self, next) {
+	return settled(self, next) || Object.keys(resultKeys).some((name) => isResultKey(name) && self.current[name] !== next[name]);
+}
+function setCurrent(self, next) {
+	self.current = next;
+	self.currentStatus = next.promise.status;
 }
 /** The result for `query` with `options`, given the last query that had data. */
 function resultOf(query, options, lastWithData) {
@@ -97,13 +106,16 @@ function resultOf(query, options, lastWithData) {
 }
 /** Observe `query`. Doesn't subscribe to it until the observer has a listener. */
 function makeUnsafe(query, options = {}) {
+	const current = resultOf(query, options, void 0);
 	return Object.assign(Object.create(Proto), {
-		current: resultOf(query, options, void 0),
+		current,
+		currentStatus: current.promise.status,
 		lastWithData: getUnsafe$1(query).hasData ? query : void 0,
 		listeners: /* @__PURE__ */ new Set(),
 		options,
 		query,
 		subscription: void 0,
+		tracked: void 0,
 		trackedProps: /* @__PURE__ */ new Set()
 	});
 }
@@ -126,7 +138,7 @@ function get(self) {
 function getOptimisticResultUnsafe(self, query, options) {
 	const impl = implOf(self);
 	const result = resultOf(query, options, impl.lastWithData);
-	if (!shallowEqual(impl.current, result)) impl.current = result;
+	if (anyChanged(impl, result)) setCurrent(impl, result);
 	return result;
 }
 /** Observe `query` with `options` from now on. */
@@ -185,22 +197,62 @@ function trackResult(self, result) {
 		return Reflect.get(target, name, receiver);
 	} });
 }
+const settledFields = /* @__PURE__ */ new Set([
+	"reason",
+	"status",
+	"value"
+]);
+/**
+* One wrapper per promise, shared by every observer, so its identity is as
+* stable as the promise's: an observer made by a render that suspended
+* before committing is replaced on the next attempt, and `use()` expects
+* the same promise again.
+*/
+const wrappers = /* @__PURE__ */ new WeakMap();
+/** Wrappers whose `status`, `value` or `reason` a reader has read. */
+const settledReads = /* @__PURE__ */ new WeakSet();
+/**
+* Wrap `promise`, the result's or one derived from it, so that reading its
+* `status`, `value` or `reason` marks its settling as tracked. A first load
+* settles its promise in place, without a new promise, so only readers of
+* those fields need to hear about it. The mark is the wrapper's, shared by
+* the observers that hand it out.
+*/
+function trackThenable(self, promise) {
+	let wrapper = wrappers.get(promise);
+	if (!wrapper) {
+		const created = new Proxy(promise, { get: (target, name) => {
+			if (settledFields.has(name)) settledReads.add(created);
+			const value = Reflect.get(target, name, target);
+			return Predicate.isFunction(value) ? value.bind(target) : value;
+		} });
+		wrappers.set(promise, created);
+		wrapper = created;
+	}
+	implOf(self).tracked = wrapper;
+	return wrapper;
+}
+function readsSettled(self) {
+	return self.tracked !== void 0 && settledReads.has(self.tracked);
+}
 /** Mark `name` as read, for bindings that track access themselves. */
 function trackProp(self, name) {
 	implOf(self).trackedProps.add(name);
 }
 /** Recompute the result, and notify listeners if a tracked property changed. */
 function updateResult(self) {
-	const previous = self.current;
 	const next = resultOf(self.query, self.options, self.lastWithData);
 	if (getUnsafe$1(self.query).hasData) self.lastWithData = self.query;
-	if (shallowEqual(previous, next)) return;
-	self.current = next;
-	if (shouldNotify(self, previous, next)) for (const listener of self.listeners) listener();
+	if (!anyChanged(self, next)) return;
+	const notify = shouldNotify(self, next);
+	setCurrent(self, next);
+	if (notify) for (const listener of self.listeners) listener();
 }
-function shouldNotify(self, previous, next) {
-	if (self.trackedProps.size === 0) return true;
-	for (const name of self.trackedProps) if (previous[name] !== next[name]) return true;
+/** Whether something tracked differs in `next` from the current result. */
+function shouldNotify(self, next) {
+	if (self.trackedProps.size === 0 && !readsSettled(self)) return true;
+	if (readsSettled(self) && settled(self, next)) return true;
+	for (const name of self.trackedProps) if (self.current[name] !== next[name]) return true;
 	return false;
 }
 /**
@@ -245,4 +297,4 @@ function poll(query, interval) {
 	}).pipe(Effect.delay(interval), Effect.forever);
 }
 //#endregion
-export { TypeId, changes, get, getOptimisticResultUnsafe, getUnsafe, isQueryObserver, make, makeUnsafe, observer_exports, setOptionsUnsafe, subscribeUnsafe, trackProp, trackResult };
+export { TypeId, changes, get, getOptimisticResultUnsafe, getUnsafe, isQueryObserver, make, makeUnsafe, observer_exports, setOptionsUnsafe, subscribeUnsafe, trackProp, trackResult, trackThenable };

package/package.json

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