Preserve nested identity
A query receives a freshly parsed response whose unchanged nested records should retain their old references.
TanStack · Function
replaceEqualDeep
Returns the previous value when it is deeply equal to the new value; otherwise, it reuses equal nested parts from the previous value. This supports structural sharing for JSON-like data.
How it works
replaceEqualDeep compares a previous value with a new value recursively. It returns the previous value when the two are deeply equal; otherwise, it builds the new result while reusing deeply equal nested parts from the previous value, which supports structural sharing for JSON-like data.
Syntax
function replaceEqualDeep<T>(a: unknown, b: T, depth?: number): T;Parameters
| Name | Type | Description |
|---|---|---|
a | unknown | The previous value, whose deeply equal parts are reused. |
b | T | The new value. |
depth | number | The current recursion depth. Past a depth of 500, b is returned as is. |
Returns
T — a if b is deeply equal to it, otherwise b with its deeply equal parts replaced by those of a.
Key points
- A completely equal new value produces the original previous reference.
- For partially changed data, unchanged nested children in the new value are replaced with references from the previous value.
- Its primary documented use is preserving shared structure across JSON-like values.
- Parameter a supplies the references that may be reused.
- Parameter b supplies the candidate result and its generic type.
- The optional depth parameter records where recursive comparison currently is.
- The return is either the old reference or a new-value-shaped result containing reused equal parts.
Common mistakes
- The optional depth tracks recursion, and values deeper than 500 levels are returned without further structural sharing.
Example: Reuse unchanged nested data
import { replaceEqualDeep } from '@tanstack/query-core'
const previous = { user: { id: 1, name: 'Ada' }, count: 1 }
const next = { user: { id: 1, name: 'Ada' }, count: 2 }
const result = replaceEqualDeep(previous, next)
console.log(result !== previous) // true
console.log(result.user === previous.user) // true
console.log(result.count) // 2Reuses the unchanged nested user object while retaining the new count.
When to use it
Minimize structural changes
A cache or state update needs a new top-level result while avoiding needless replacement of equal subtrees.
Share JSON data structure
Recursive comparison of JSON-compatible query data should share unchanged branches.
Interview questions
QWhat does replaceEqualDeep do when two values differ only in some nested fields?
It accepts a previous value and a new value, then returns the previous value when they are deeply equal. When they differ, unchanged deeply equal children from the previous value are reused in the returned new value.
Follow-up: What happens with very deeply nested input? The documented recursion depth limit means that after depth 500, the new value is returned as-is.
QExplain the parameters and return type.
The first parameter is the previous value and may be unknown. The second parameter is the new value and determines the generic return type T; the optional third parameter represents the current recursion depth.
Follow-up: Why can the first parameter be unknown? The function only requires it as a source of potentially reusable deeply equal parts, while the returned shape is typed from the new value.
QWhy is this function useful in query-data processing?
It is useful for structural sharing between JSON values. Reusing unchanged references can preserve identity for unaffected subtrees and avoid treating those subtrees as changed.
Follow-up: What should be considered before applying it to arbitrary data? The documentation specifically describes JSON values, so non-JSON structures should not be assumed to receive equivalent handling.
Related
structural sharingquery-corereplaceEqualDeep