Merge branch 'main' into main

.all-contributorsrc

@@ -275,7 +275,10 @@
       "login": "Newbie012",
       "name": "Eliya Cohen",
       "avatar_url": "https://avatars.githubusercontent.com/u/10504365?v=4",
-      "profile": "https://github.com/Newbie012"
+      "profile": "https://github.com/Newbie012",
+      "contributions": [
+        "code"
+      ]
     },
     {
       "login": "KubaJastrz",
@@ -285,6 +288,15 @@
       "contributions": [
         "code"
       ]
+    },
+    {
+      "login": "balazsmatepetro",
+      "name": "Balázs Máté Petró",
+      "avatar_url": "https://avatars.githubusercontent.com/u/1608725?v=4",
+      "profile": "https://github.com/balazsmatepetro",
+      "contributions": [
+        "code"
+      ]
     }
   ],
   "contributorsPerLine": 7,

README.md

@@ -98,6 +98,7 @@ Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/d
     </tr>
     <tr>
       <td align="center"><a href="https://kubajastrz.com"><img src="https://avatars.githubusercontent.com/u/6443113?v=4?s=100" width="100px;" alt="Jakub Jastrzębski"/><br /><sub><b>Jakub Jastrzębski</b></sub></a><br /><a href="https://github.com/TanStack/query/commits?author=KubaJastrz" title="Code">💻</a></td>
+      <td align="center"><a href="https://github.com/balazsmatepetro"><img src="https://avatars.githubusercontent.com/u/1608725?v=4?s=100" width="100px;" alt="Balázs Máté Petró"/><br /><sub><b>Balázs Máté Petró</b></sub></a><br /><a href="https://github.com/TanStack/query/commits?author=balazsmatepetro" title="Code">💻</a></td>
     </tr>
   </tbody>
 </table>

docs/eslint/eslint-plugin-query.md

@@ -10,11 +10,11 @@ TanStack Query comes with its own ESLint plugin. This plugin is used to enforce
 The plugin is a separate package that you need to install:
 
 ```bash
-$ npm i @tanstack/eslint-plugin-query
+$ npm i -D @tanstack/eslint-plugin-query
 # or
-$ pnpm add @tanstack/eslint-plugin-query
+$ pnpm add -D @tanstack/eslint-plugin-query
 # or
-$ yarn add @tanstack/eslint-plugin-query
+$ yarn add -D @tanstack/eslint-plugin-query
 ```
 
 ## Usage

docs/guides/disabling-queries.md

@@ -25,7 +25,7 @@ function Todos() {
     isFetching
   } = useQuery({
     queryKey: ['todos'],
-    queyFn: fetchTodoList,
+    queryFn: fetchTodoList,
     enabled: false,
   })
 

docs/guides/prefetching.md

@@ -8,7 +8,10 @@ If you're lucky enough, you may know enough about what your users will do to be
 ```tsx
 const prefetchTodos = async () => {
   // The results of this query will be cached like a normal query
-  await queryClient.prefetchQuery(['todos'], fetchTodos)
+  await queryClient.prefetchQuery({
+    queryKey: ['todos'],
+    queryFn: fetchTodos,
+  })
 }
 ```
 

docs/guides/ssr.md

@@ -236,7 +236,7 @@ async function handleRequest (req, res) {
 
 ### Client
 
-Make sure to [use suspense in your queries](./suspense.md).
+Make sure to [use suspense in your queries](../guides/suspense).
 
 ## Tips, Tricks and Caveats
 

docs/guides/updates-from-mutation-responses.md

@@ -44,3 +44,29 @@ const useMutateTodo = () => {
   })
 }
 ```
+
+## Immutability
+
+Updates via `setQueryData` must be performed in an _immutable_ way. **DO NOT** attempt to write directly to the cache by mutating data (that you retrieved via from the cache) in place. It might work at first but can lead to subtle bugs along the way.
+
+```tsx
+queryClient.setQueryData(
+  ['posts', { id }],
+  (oldData) => {
+    if (oldData) {
+      // ❌ do not try this
+      oldData.title = 'my new post title'
+    }
+    return oldData
+  })
+```
+
+```tsx
+queryClient.setQueryData(
+  ['posts', { id }],
+  // ✅ this is the way
+  (oldData) => oldData ? {
+    ...oldData,
+    title: 'my new post title'
+  } : oldData
+```

docs/reference/QueryClient.md

@@ -237,6 +237,10 @@ setQueryData(queryKey, oldData => newData)
 
 If the updater function returns `undefined`, the query data will not be updated. If the updater function receives `undefined` as input, you can return `undefined` to bail out of the update and thus _not_ create a new cache entry.
 
+**Immutability**
+
+Updates via `setQueryData` must be performed in an _immuatable_ way. **DO NOT** attempt to write directly to the cache by mutating `oldData` or data that you retrieved via `getQueryData` in place.
+
 ## `queryClient.getQueryState`
 
 `getQueryState` is a synchronous function that can be used to get an existing query's state. If the query does not exist, `undefined` will be returned.

examples/vue/2.6-basic/.gitignore

@@ -0,0 +1,9 @@
+node_modules
+.DS_Store
+dist
+dist-ssr
+*.local
+
+package-lock.json
+yarn.lock
+pnpm-lock.yaml

examples/vue/2.6-basic/README.md

@@ -0,0 +1,6 @@
+# 2.6 Basic example
+
+To run this example:
+
+- `npm install` or `yarn` or `pnpm i`
+- `npm run dev` or `yarn dev` or `pnpm dev`

examples/vue/2.6-basic/index.html

@@ -0,0 +1,12 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Vue Query Example</title>
+  </head>
+  <body>
+    <div id="app"></div>
+    <script type="module" src="/src/main.ts"></script>
+  </body>
+</html>

examples/vue/2.6-basic/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "@tanstack/query-example-vue-2.6-basic",
+  "private": true,
+  "scripts": {
+    "dev": "vite",
+    "build": "vite build",
+    "build:dev": "vite build -m development",
+    "serve": "vite preview"
+  },
+  "dependencies": {
+    "@tanstack/vue-query": "4.13.3",
+    "@vue/composition-api": "1.4.4",
+    "vue": "2.6.14",
+    "vue-template-compiler": "2.6.14"
+  },
+  "devDependencies": {
+    "typescript": "4.8.4",
+    "vite": "3.1.0",
+    "vite-plugin-vue2": "2.0.2"
+  }
+}

examples/vue/2.6-basic/src/App.vue

@@ -0,0 +1,45 @@
+<script lang="ts">
+import { defineComponent, ref } from '@vue/composition-api'
+
+import Posts from './Posts.vue'
+import Post from './Post.vue'
+
+export default defineComponent({
+  name: 'App',
+  components: { Posts, Post },
+  setup() {
+    const visitedPosts = ref(new Set())
+    const isVisited = (id: number) => visitedPosts.value.has(id)
+
+    const postId = ref(-1)
+    const setPostId = (id: number) => {
+      visitedPosts.value.add(id)
+      postId.value = id
+    }
+
+    return {
+      isVisited,
+      postId,
+      setPostId,
+    }
+  },
+})
+</script>
+
+<template>
+  <div>
+    <h1>Vue Query - Basic</h1>
+    <p>
+      As you visit the posts below, you will notice them in a loading state the
+      first time you load them. However, after you return to this list and click
+      on any posts you have already visited again, you will see them load
+      instantly and background refresh right before your eyes!
+      <strong>
+        (You may need to throttle your network speed to simulate longer loading
+        sequences)
+      </strong>
+    </p>
+    <Post v-if="postId > -1" :postId="postId" @setPostId="setPostId" />
+    <Posts v-else :isVisited="isVisited" @setPostId="setPostId" />
+  </div>
+</template>

examples/vue/2.6-basic/src/Post.vue

@@ -0,0 +1,53 @@
+<script lang="ts">
+import { defineComponent, toRaw } from '@vue/composition-api'
+import { useQuery } from '@tanstack/vue-query'
+
+import { Post } from './types'
+
+const fetcher = async (id: number): Promise<Post> =>
+  await fetch(`https://jsonplaceholder.typicode.com/posts/${id}`).then(
+    (response) => response.json(),
+  )
+
+export default defineComponent({
+  name: 'PostDetails',
+  props: {
+    postId: {
+      type: Number,
+      required: true,
+    },
+  },
+  emits: ['setPostId'],
+  setup(props) {
+    const { isLoading, isError, isFetching, data, error } = useQuery(
+      ['post', props.postId],
+      () => fetcher(props.postId),
+    )
+
+    return { isLoading, isError, isFetching, data, error }
+  },
+})
+</script>
+
+<template>
+  <div>
+    <h1>Post {{ postId }}</h1>
+    <a @click="$emit('setPostId', -1)" href="#"> Back </a>
+    <div v-if="isLoading" class="update">Loading...</div>
+    <div v-else-if="isError">An error has occurred: {{ error }}</div>
+    <div v-else-if="data">
+      <h1>{{ data.title }}</h1>
+      <div>
+        <p>{{ data.body }}</p>
+      </div>
+      <div v-if="isFetching" class="update">Background Updating...</div>
+    </div>
+  </div>
+</template>
+
+<style scoped>
+.update {
+  font-weight: bold;
+  color: green;
+}
+</style>

examples/vue/2.6-basic/src/Posts.vue

@@ -0,0 +1,57 @@
+<script lang="ts">
+import { defineComponent } from '@vue/composition-api'
+import { useQuery } from '@tanstack/vue-query'
+
+import type { Post } from './types'
+
+const fetcher = async (): Promise<Post[]> =>
+  await fetch('https://jsonplaceholder.typicode.com/posts').then((response) =>
+    response.json(),
+  )
+
+export default defineComponent({
+  name: 'PostsList',
+  props: {
+    isVisited: {
+      type: Function,
+      required: true,
+    },
+  },
+  emits: ['setPostId'],
+  setup() {
+    const { isLoading, isError, isFetching, data, error, refetch } = useQuery(
+      ['posts'],
+      fetcher,
+    )
+
+    return { isLoading, isError, isFetching, data, error, refetch }
+  },
+})
+</script>
+
+<template>
+  <div>
+    <h1>Posts</h1>
+    <div v-if="isLoading">Loading...</div>
+    <div v-else-if="isError">An error has occurred: {{ error }}</div>
+    <div v-else-if="data">
+      <ul>
+        <li v-for="item in data" :key="item.id">
+          <a
+            @click="$emit('setPostId', item.id)"
+            href="#"
+            :class="{ visited: isVisited(item.id) }"
+            >{{ item.title }}</a
+          >
+        </li>
+      </ul>
+    </div>
+  </div>
+</template>
+
+<style scoped>
+.visited {
+  font-weight: bold;
+  color: green;
+}
+</style>

examples/vue/2.6-basic/src/main.ts

@@ -0,0 +1,14 @@
+import Vue from 'vue'
+import VueCompositionApi, { createApp, h } from '@vue/composition-api'
+import { VueQueryPlugin } from '@tanstack/vue-query'
+
+import App from './App.vue'
+
+Vue.use(VueCompositionApi)
+Vue.use(VueQueryPlugin)
+
+createApp({
+  render() {
+    return h(App)
+  },
+}).mount('#app')

examples/vue/2.6-basic/src/shims-vue.d.ts

@@ -0,0 +1,4 @@
+declare module '*.vue' {
+  import Vue from 'vue'
+  export default Vue
+}

examples/vue/2.6-basic/src/types.d.ts

@@ -0,0 +1,6 @@
+export interface Post {
+  userId: number
+  id: number
+  title: string
+  body: string
+}

examples/vue/2.6-basic/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "compilerOptions": {
+    "target": "esnext",
+    "module": "esnext",
+    "moduleResolution": "node",
+    "strict": true,
+    "jsx": "preserve",
+    "sourceMap": true,
+    "resolveJsonModule": true,
+    "esModuleInterop": true,
+    "lib": ["esnext", "dom"],
+    "types": ["vite/client"]
+  },
+  "include": ["src/**/*.ts", "src/**/*.d.ts", "src/**/*.vue"]
+}

examples/vue/2.6-basic/vite.config.ts

@@ -0,0 +1,7 @@
+import { defineConfig } from 'vite'
+import { createVuePlugin } from 'vite-plugin-vue2'
+
+// https://vitejs.dev/config/
+export default defineConfig({
+  plugins: [createVuePlugin()],
+})

examples/vue/basic/.gitignore

@@ -3,4 +3,7 @@ node_modules
 dist
 dist-ssr
 *.local
+
 package-lock.json
+yarn.lock
+pnpm-lock.yaml

examples/vue/basic/README.md

@@ -2,5 +2,5 @@
 
 To run this example:
 
-- `npm install` or `yarn`
-- `npm run dev` or `yarn dev`
+- `npm install` or `yarn` or `pnpm i`
+- `npm run dev` or `yarn dev` or `pnpm dev`