docs: prefer object syntax in docs (#4409)

* docs: useQuery to object syntax

* docs: invalidateQueries to object syntax

* docs: useMutation to object syntax

* docs: infinite query and other references to object syntax

Author: TkDodo

docs/adapters/react-query.md

@@ -12,7 +12,7 @@ import { QueryClient, QueryClientProvider, useQuery } from '@tanstack/react-quer
 const queryClient = new QueryClient()
 
 function Example() {
-  const query = useQuery(['todos'], fetchTodos)
+  const query = useQuery({ queryKey: ['todos'], queryFn: fetchTodos })
 
   return (
     <div>

docs/adapters/vue-query.md

@@ -20,13 +20,14 @@ import { useQueryClient, useQuery, useMutation } from "@tanstack/vue-query";
 const queryClient = useQueryClient();
 
 // Query
-const { isLoading, isError, data, error } = useQuery(["todos"], getTodos);
+const { isLoading, isError, data, error } = useQuery({ queryKey: ['todos'], queryFn: getTodos });
 
 // Mutation
-const mutation = useMutation(postTodo, {
+const mutation = useMutation({
+  mutationFn: postTodo,
   onSuccess: () => {
     // Invalidate and refetch
-    queryClient.invalidateQueries(["todos"]);
+    queryClient.invalidateQueries({ queryKey: ["todos"] });
   },
 });
 

docs/community/lukemorales-query-key-factory.md

@@ -60,12 +60,13 @@ import { queryKeys, completeTodo, fetchSingleTodo } from '../my-api'
 export function Todo({ todoId }) {
   const queryClient = useQueryClient()
 
-  const query = useQuery(queryKeys.todos.byId(todoId), fetchSingleTodo)
+  const query = useQuery({ queryKey: queryKeys.todos.byId(todoId), queryFn: fetchSingleTodo })
 
-  const mutation = useMutation(completeTodo, {
+  const mutation = useMutation({
+    mutationFn: () => completeTodo,
     onSuccess: () => {
       // Invalidate and refetch
-      queryClient.invalidateQueries(queryKeys.todos.completed)
+      queryClient.invalidateQueries({ queryKey: queryKeys.todos.completed })
     },
   })
 

docs/comparison.md

@@ -69,7 +69,7 @@ Feature/Capability Key:
 
 > **<sup>3</sup> Partial query matching** - Because React Query uses deterministic query key serialization, this allows you to manipulate variable groups of queries without having to know each individual query-key that you want to match, eg. you can refetch every query that starts with `todos` in its key, regardless of variables, or you can target specific queries with (or without) variables or nested properties, and even use a filter function to only match queries that pass your specific conditions.
 
-> **<sup>4</sup> Pre-usage Query Configuration** - This is simply a fancy name for being able to configure how queries and mutations will behave before they are used. For instance, a query can be fully configured with defaults beforehand and when the time comes to use it, only `useQuery(key)` is necessary, instead of being required to pass the fetcher and/or options with every usage. SWR does have a partial form of this feature by allowing you to pre-configure a default fetcher, but only as a global fetcher, not on a per-query basis and definitely not for mutations.
+> **<sup>4</sup> Pre-usage Query Configuration** - This is simply a fancy name for being able to configure how queries and mutations will behave before they are used. For instance, a query can be fully configured with defaults beforehand and when the time comes to use it, only `useQuery({ queryKey })` is necessary, instead of being required to pass the fetcher and/or options with every usage. SWR does have a partial form of this feature by allowing you to pre-configure a default fetcher, but only as a global fetcher, not on a per-query basis and definitely not for mutations.
 
 > **<sup>5</sup> Automatic Refetch after Mutation** - For truly automatic refetching to happen after a mutation occurs, a schema is necessary (like the one graphQL provides) along with heuristics that help the library know how to identify individual entities and entities types in that schema.
 

docs/graphql.md

@@ -33,15 +33,16 @@ const allFilmsWithVariablesQueryDocument = graphql(/* GraphQL */ `
 
 function App() {
   // `data` is fully typed!
-  const { data } = useQuery(['films'], async () =>
-    request(
-      'https://swapi-graphql.netlify.app/.netlify/functions/index',
-      allFilmsWithVariablesQueryDocument,
-      // variables are type-checked too!
-      { first: 10 }
-    )
-  );
-
+  const { data } = useQuery({
+    queryKey: ['films'],
+    queryFn: async () =>
+      request(
+        'https://swapi-graphql.netlify.app/.netlify/functions/index',
+        allFilmsWithVariablesQueryDocument,
+        // variables are type-checked too!
+        {first: 10}
+      ),
+  })
   // ...
 }
 ```

docs/guides/background-fetching-indicators.md

@@ -7,10 +7,10 @@ A query's `status === 'loading'` state is sufficient enough to show the initial
 
 ```tsx
 function Todos() {
-  const { status, data: todos, error, isFetching } = useQuery(
-    ['todos'],
-    fetchTodos
-  )
+  const { status, data: todos, error, isFetching } = useQuery({
+      queryKey: ['todos'],
+      queryFn: fetchTodos,
+  })
 
   return status === 'loading' ? (
     <span>Loading...</span>

docs/guides/caching.md

@@ -16,18 +16,18 @@ This caching example illustrates the story and lifecycle of:
 
 Let's assume we are using the default `cacheTime` of **5 minutes** and the default `staleTime` of `0`.
 
-- A new instance of `useQuery(['todos'], fetchTodos)` mounts.
+- A new instance of `useQuery({ queryKey: ['todos'], queryFn: fetchTodos })` mounts.
   - Since no other queries have been made with the `['todos']` query key, this query will show a hard loading state and make a network request to fetch the data.
   - When the network request has completed, the returned data will be cached under the `['todos']` key.
   - The hook will mark the data as stale after the configured `staleTime` (defaults to `0`, or immediately).
-- A second instance of `useQuery(['todos'], fetchTodos)` mounts elsewhere.
+- A second instance of `useQuery({ queyKey: ['todos'], queryFn: fetchTodos })` mounts elsewhere.
   - Since the cache already has data for the `['todos']` key from the first query, that data is immediately returned from the cache.
   - The new instance triggers a new network request using its query function.
     - Note that regardless of whether both `fetchTodos` query functions are identical or not, both queries' [`status`](../reference/useQuery) are updated (including `isFetching`, `isLoading`, and other related values) because they have the same query key.
   - When the request completes successfully, the cache's data under the `['todos']` key is updated with the new data, and both instances are updated with the new data.
-- Both instances of the `useQuery(['todos'], fetchTodos)` query are unmounted and no longer in use.
+- Both instances of the `useQuery({ queryKey: ['todos'], queryFn: fetchTodos })` query are unmounted and no longer in use.
   - Since there are no more active instances of this query, a cache timeout is set using `cacheTime` to delete and garbage collect the query (defaults to **5 minutes**).
-- Before the cache timeout has completed, another instance of `useQuery(['todos'], fetchTodos)` mounts. The query immediately returns the available cached data while the `fetchTodos` function is being run in the background. When it completes successfully, it will populate the cache with fresh data.
-- The final instance of `useQuery(['todos'], fetchTodos)` unmounts.
-- No more instances of `useQuery(['todos'], fetchTodos)` appear within **5 minutes**.
+- Before the cache timeout has completed, another instance of `useQuery({ queryKey: ['todos'], queyFn: fetchTodos })` mounts. The query immediately returns the available cached data while the `fetchTodos` function is being run in the background. When it completes successfully, it will populate the cache with fresh data.
+- The final instance of `useQuery({ queryKey: ['todos'], queryFn: fetchTodos })` unmounts.
+- No more instances of `useQuery({ queyKey: ['todos'], queryFn: fetchTodos })` appear within **5 minutes**.
   - The cached data under the `['todos']` key is deleted and garbage collected.

docs/guides/default-query-function.md

@@ -31,14 +31,15 @@ function App() {
 
 // All you have to do now is pass a key!
 function Posts() {
-  const { status, data, error, isFetching } = useQuery(['/posts'])
+  const { status, data, error, isFetching } = useQuery({ queryKey: ['/posts'] })
 
   // ...
 }
 
 // You can even leave out the queryFn and just go straight into options
 function Post({ postId }) {
-  const { status, data, error, isFetching } = useQuery([`/posts/${postId}`], {
+  const { status, data, error, isFetching } = useQuery({
+    queryKey: [`/posts/${postId}`],
     enabled: !!postId,
   })
 

docs/guides/dependent-queries.md

@@ -7,18 +7,16 @@ Dependent (or serial) queries depend on previous ones to finish before they can
 
 ```tsx
 // Get the user
-const { data: user } = useQuery(['user', email], getUserByEmail)
+const { data: user } = useQuery({ queryKey: ['user', email], queryFn: getUserByEmail })
 
 const userId = user?.id
 
 // Then get the user's projects
-const { status, fetchStatus, data: projects } = useQuery(
-  ['projects', userId],
-  getProjectsByUser,
-  {
-    // The query will not execute until the userId exists
-    enabled: !!userId,
-  }
+const { status, fetchStatus, data: projects } = useQuery({
+  queryKey: ['projects', userId],
+  queryFn: getProjectsByUser,
+  // The query will not execute until the userId exists
+  enabled: !!userId,
 )
 ```
 

docs/guides/disabling-queries.md

@@ -25,7 +25,9 @@ function Todos() {
     error,
     refetch,
     isFetching
-  } = useQuery(['todos'], fetchTodoList, {
+  } = useQuery({
+    queryKey: ['todos'],
+    queyFn: fetchTodoList,
     enabled: false,
   })
 
@@ -69,14 +71,12 @@ The enabled option can not only be used to permanently disable a query, but also
 function Todos() {
   const [filter, setFilter] = React.useState('')
 
-  const { data } = useQuery(
-    ['todos', filter],
-    () => fetchTodos(filter),
-    {
+  const { data } = useQuery({
+      queryKey: ['todos', filter],
+      queryFn: () => fetchTodos(filter),
       // ⬇️ disabled as long as the filter is empty
       enabled: !!filter
-    }
-  )
+  })
 
   return (
       <div>