@raf-query/core 0.0.9 → 0.0.11

package/CHANGELOG.md

@@ -1,10 +1,20 @@
 # Changelog
 
+## [0.0.11](https://github.com/KATT/raf-query/compare/0.0.10...0.0.11) (2026-10-12)
+
+### Features
+
+* **core:** structurally share new data with the old (structuralSharing) ([#15](https://github.com/KATT/raf-query/issues/15)) ([bf4392a](https://github.com/KATT/raf-query/commit/bf4392a56936ead6fb8b2726981cb19dadf51304))
+
+## [0.0.10](https://github.com/KATT/raf-query/compare/0.0.9...0.0.10) (2026-10-12)
+
+- move the TanStack Query experiment into .experimental folders ([#12](https://github.com/KATT/raf-query/issues/12)) ([e9613a6](https://github.com/KATT/raf-query/commit/e9613a608f100fb17de6baf37c0f1fcfa479e909))
+
 ## [0.0.9](https://github.com/KATT/raf-query/compare/0.0.8...0.0.9) (2026-10-12)
 
 ### Bug Fixes
 
-* **examples:** let the client pick new comment ids ([#9](https://github.com/KATT/raf-query/issues/9)) ([de3a723](https://github.com/KATT/raf-query/commit/de3a7238b2568458a9771450a8c94d82576f5f7d))
+- **examples:** let the client pick new comment ids ([#9](https://github.com/KATT/raf-query/issues/9)) ([de3a723](https://github.com/KATT/raf-query/commit/de3a7238b2568458a9771450a8c94d82576f5f7d))
 
 ## [0.0.8](https://github.com/KATT/raf-query/compare/0.0.7...0.0.8) (2026-10-12)
 

package/README.md

@@ -179,7 +179,7 @@ function PostPage() {
 | `hash`         | Stable string form of the handle's key, for `key` props on Suspense boundaries                                           |
 | `refetch()`    | Refetch now. Returns a promise, so it can be awaited inside a transition or action                                       |
 
-When the cache updates — refetch, invalidation, `setData` — the hook returns a new, pre-resolved promise and the component re-renders without suspending. When the **first** load fails, the promise rejects and `use()` throws to the nearest error boundary. Resetting that boundary refetches the query.
+When the cache updates — refetch, invalidation, `setData` — the hook returns a new, pre-resolved promise and the component re-renders without suspending. New data is structurally shared with the old: objects and arrays that are deeply equal keep their identity, and a refetch that returns equal data keeps the same promise, so nothing re-renders. When the **first** load fails, the promise rejects and `use()` throws to the nearest error boundary. Resetting that boundary refetches the query.
 
 Queries do not refetch on mount. They refetch when a loader starts them again, when invalidated, on window focus or reconnect while stale, on `refetch()`, or on `refetchInterval`.
 
@@ -539,6 +539,7 @@ Query options, accepted by `queryOptions`, `infiniteQueryOptions` and `config.de
 | `retry` (count, `boolean`, predicate, `Schedule`)     | `3`; `0` on the server                    |
 | `retryDelay` (ms, or a function of the failure count) | Doubling from 1 s, at most 30 s           |
 | `refetchOnWindowFocus`, `refetchOnReconnect`          | `true` (only read, stale queries refetch) |
+| `structuralSharing` (keep deeply equal parts of data) | `true`                                    |
 
 `infiniteQueryOptions` also takes `getPreviousPageParam` and `maxPages`.
 

package/dist/key.mjs

@@ -33,4 +33,4 @@ function matchesKey(key, prefix) {
 	return prefix.length <= key.length && prefix.every((part, index) => partialMatch(key[index], part));
 }
 //#endregion
-export { hashKey, matchesKey };
+export { hashKey, isPlainRecord, matchesKey };

package/dist/options.d.mts

@@ -34,6 +34,12 @@ export interface QueryBehavior {
   readonly retryDelay?: number | ((failureCount: number, error: unknown) => number);
   /** How long data counts as fresh, in ms. Fresh data is never refetched. */
   readonly staleTime?: number;
+  /**
+   * Keep the parts of new data that are deeply equal to the old data, so
+   * unchanged objects keep their identity and unchanged data keeps its
+   * promise. Compares plain objects and arrays. Default `true`.
+   */
+  readonly structuralSharing?: boolean;
 }
 export interface QueryOptions<TData> extends QueryBehavior {
   readonly kind: "query";

package/dist/query.mjs

@@ -1,4 +1,5 @@
 import { scheduleNotify } from "./notify.mjs";
+import { replaceEqualDeep } from "./share.mjs";
 import { fulfilled, pending } from "./thenable.mjs";
 import { Cause, Effect, Exit, Predicate, Schedule } from "effect";
 //#region src/query.ts
@@ -260,10 +261,8 @@ var QueryEntry = class {
 	#settle(run, exit) {
 		if (this.#inFlight !== run) return;
 		this.#inFlight = void 0;
-		if (Exit.isSuccess(exit)) {
-			this.#succeed(exit.value, Date.now());
-			run.deferred.resolve(exit.value);
-		} else if (Cause.hasInterruptsOnly(exit.cause)) {
+		if (Exit.isSuccess(exit)) run.deferred.resolve(this.#succeed(exit.value, Date.now()));
+		else if (Cause.hasInterruptsOnly(exit.cause)) {
 			this.#set({
 				fetchDirection: void 0,
 				isFetching: false
@@ -276,10 +275,13 @@ var QueryEntry = class {
 		}
 		this.#scheduleGc();
 	}
-	#succeed(data, updatedAt) {
+	#succeed(next, updatedAt) {
+		const previous = this.#state;
+		const data = previous.hasData && this.#behavior("structuralSharing") !== false ? replaceEqualDeep(previous.data, next) : next;
 		const firstLoad = this.#pending;
 		this.#pending = void 0;
 		firstLoad?.resolve(data);
+		const unchanged = previous.hasData && data === previous.data;
 		this.#set({
 			data,
 			error: null,
@@ -288,10 +290,11 @@ var QueryEntry = class {
 			hasData: true,
 			isFetching: false,
 			isInvalidated: false,
-			promise: firstLoad ? firstLoad.promise : fulfilled(data),
+			promise: firstLoad?.promise ?? (unchanged ? previous.promise : fulfilled(data)),
 			status: "success",
 			updatedAt
 		});
+		return data;
 	}
 	#fail(error) {
 		this.#host.reportError(error, this);

package/dist/share.mjs

@@ -0,0 +1,41 @@
+import { unsafeCast } from "./cast.mjs";
+import { isPlainRecord } from "./key.mjs";
+//#region src/share.ts
+function isPlainArray(value) {
+	return Array.isArray(value) && value.length === Object.keys(value).length;
+}
+function share(previous, next, depth) {
+	if (previous === next || depth > 500) return next;
+	if (isPlainArray(previous) && isPlainArray(next)) {
+		let equal = previous.length === next.length;
+		const copy = next.map((item, index) => {
+			const shared = share(previous[index], item, depth + 1);
+			equal &&= shared === previous[index];
+			return shared;
+		});
+		return equal ? previous : copy;
+	}
+	if (isPlainRecord(previous) && isPlainRecord(next)) {
+		const names = Object.keys(next);
+		let equal = names.length === Object.keys(previous).length;
+		const copy = {};
+		for (const name of names) {
+			const shared = share(previous[name], next[name], depth + 1);
+			equal &&= shared === previous[name] && Object.hasOwn(previous, name);
+			copy[name] = shared;
+		}
+		return equal ? previous : copy;
+	}
+	return next;
+}
+/**
+* `next`, reusing every part of `previous` that is deeply equal to it: all
+* of `previous` when nothing changed, else a copy of `next` whose unchanged
+* subtrees are `previous`'s. Only plain objects and arrays are compared;
+* anything else is taken from `next`. TanStack Query's `replaceEqualDeep`.
+*/
+function replaceEqualDeep(previous, next) {
+	return unsafeCast(share(previous, next, 0));
+}
+//#endregion
+export { replaceEqualDeep };

package/package.json

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