Skip to content

docs: Clarify that useQuery results are immutable #9108

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
May 6, 2025
Merged

Conversation

ericyd
Copy link
Contributor

@ericyd ericyd commented May 5, 2025

This PR probably feels unnecessary to the maintainers, but it caused some confusion for me and seems to come up from time to time in various discussions and issue reports, e.g.

In React, immutability is a core design choice baked into most operations. For React, immutable data should be intuitive for most developers.

In contrast, Vue treats mutability as a feature, even highlighting deep reactivity in their documentation and providing recommendations on two-way bindings with v-model. For the average Vue developer, I would wager that the default assumption is that data is mutable.

useQuery properly annotates the data as readonly in TypeScript. However, the TypeScript compiler (at least as of 5.8.3) does not protect against all operations on readonly objects. For example, this is valid and compiles just fine:

const immutable: Readonly<Record<string, boolean[]>> = { list: [true] }
immutable.list.push(false)

(Of course, assignment is forbidden):

const immutable: Readonly<Record<string, boolean[]>> = { list: [true] }
immutable.list = [false]
^^^^^^^^^^^^^^
Index signature in type 'Readonly<Record<string, boolean[]>>' only permits reading.

In addition Vue provides a warning when immutable object mutations are attempted. However, warnings can be easy to overlook and this can lead to bugs.

Therefore, I believe being explicit about immutability is a useful contribution for the Vue framework docs.

@github-actions github-actions bot added the documentation Improvements or additions to documentation label May 5, 2025
@TkDodo TkDodo merged commit 127bd01 into TanStack:main May 6, 2025
1 check passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
documentation Improvements or additions to documentation
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants