docs: add parallel and dependant queries docs

Author: DamianOsipiuk

docs/_sidebar.md

@@ -21,5 +21,7 @@
   - [Queries](guides/queries.md)
   - [Query Keys](guides/query-keys.md)
   - [Query Functions](guides/query-functions.md)
+  - [Parallel Queries](guides/parallel-queries.md)
+  - [Dependent Queries](guides/dependent-queries.md)
   - [Custom clients (experimental)](guides/custom-clients.md)
   - [SSR & Nuxt.js (experimental)](guides/ssr.md)

docs/guides/dependent-queries.md

@@ -0,0 +1,22 @@
+Dependent (or serial) queries depend on previous ones to finish before they can execute. To achieve this, it's as easy as using the `enabled` option to tell a query when it is ready to run:
+
+```js
+// Get the user
+const { data: user } = useQuery(["user", email], getUserByEmail);
+
+const userId = computed(() => user.value?.id);
+const enabled = computed(() => !!user.value?.id);
+
+// Then get the user's projects
+const { isIdle, data: projects } = useQuery(
+  reactive(["projects", { userId }]),
+  () => getProjectsByUser(userId.value),
+  reactive({
+    // The query will not execute until the userId exists
+    enabled,
+  })
+);
+
+// isIdle will be `true` until `enabled` is true and the query begins to fetch.
+// It will then go to the `isLoading` stage and hopefully the `isSuccess` stage :)
+```

docs/guides/parallel-queries.md

@@ -0,0 +1,33 @@
+"Parallel" queries are queries that are executed in parallel, or at the same time so as to maximize fetching concurrency.
+
+## Manual Parallel Queries
+
+When the number of parallel queries does not change, there is **no extra effort** to use parallel queries. Just use any number of Vue Query's `useQuery` and `useInfiniteQuery` hooks side-by-side!
+
+```js
+// The following queries will execute in parallel
+const usersQuery = useQuery('users', fetchUsers)
+const teamsQuery = useQuery('teams', fetchTeams)
+const projectsQuery = useQuery('projects', fetchProjects)
+...
+```
+
+> When using Vue Query in suspense mode, this pattern of parallelism does not work, since the first query would suspend the setup function before the other queries run. To get around this, you'll either need to use the `useQueries` hook (which is suggested) or orchestrate your own parallelism with separate components for each `useQuery` instance (which is lame).
+
+## Dynamic Parallel Queries with `useQueries`
+
+If the number of queries you need to execute is changing from render to render, you cannot use manual querying since that would violate the rules of hooks. Instead, Vue Query provides a `useQueries` hook, which you can use to dynamically execute as many queries in parallel as you'd like.
+
+`useQueries` accepts an **array of query options objects** and returns an **array of query results**:
+
+```js
+const users = computed(...)
+const userQueries = useQueries(
+  users.value.map(user => {
+    return {
+      queryKey: ['user', {userId: user.id}],
+      queryFn: () => fetchUserById(user.id),
+    }
+  })
+)
+```

docs/guides/queries.md

@@ -12,11 +12,7 @@ The **unique key** you provide is used internally for refetching, caching, and s
 The query results returned by `useQuery` contains all of the information about the query that you'll need for templating and any other usage of the data:
 
 ```js
-import { useQuery } from "vue-query";
-
-function App() {
-  const result = useQuery("todos", fetchTodoList);
-}
+const result = useQuery("todos", fetchTodoList);
 ```
 
 The `result` object contains a few very important states you'll need to be aware of to be productive. A query can only be in one of the following states at any given moment:
@@ -71,10 +67,7 @@ import { useQuery } from "vue-query";
 export default defineComponent({
   name: "Todo",
   setup(props) {
-    const { status, data, error } = useQuery(
-      "todos",
-      fetchTodoList
-    );
+    const { status, data, error } = useQuery("todos", fetchTodoList);
     return { status, data, error };
   },
 });
@@ -88,4 +81,4 @@ export default defineComponent({
     <li v-for="todo in data" :key="todo.id">{{ todo.title }}</li>
   </ul>
 </template>
-```
+```