docs: typescript example (#1400)

* (docs): add typescript example for optimistic updates

* (docs): add a Counter to show off the "select" option in TypeScript

* (docs): simplify TypeScript example

There is no need to add generics to userQuery now - it will be inferred correctly by the options

* return context from onMutate and define types on the `onMutate` function

* add missing select option to useQuery api reference

docs/src/pages/reference/useQuery.md

@@ -39,6 +39,7 @@ const {
   refetchOnWindowFocus,
   retry,
   retryDelay,
+  select
   staleTime,
   structuralSharing,
   suspense,

examples/optimistic-updates-typescript/.gitignore

@@ -0,0 +1,26 @@
+# See https://help.github.com/articles/ignoring-files/ for more about ignoring files.
+
+# dependencies
+/node_modules
+/.pnp
+.pnp.js
+
+# testing
+/coverage
+
+# production
+/build
+
+yarn.lock
+package-lock.json
+
+# misc
+.DS_Store
+.env.local
+.env.development.local
+.env.test.local
+.env.production.local
+
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*

examples/optimistic-updates-typescript/README.md

@@ -0,0 +1,6 @@
+# Example
+
+To run this example:
+
+- `npm install` or `yarn`
+- `npm run dev` or `yarn dev`

examples/optimistic-updates-typescript/next-env.d.ts

@@ -0,0 +1,2 @@
+/// <reference types="next" />
+/// <reference types="next/types/global" />

examples/optimistic-updates-typescript/next.config.js

@@ -0,0 +1,48 @@
+const Module = require('module')
+const path = require('path')
+const resolveFrom = require('resolve-from')
+
+const node_modules = path.resolve(__dirname, 'node_modules')
+
+const originalRequire = Module.prototype.require
+
+// The following ensures that there is always only a single (and same)
+// copy of React in an app at any given moment.
+Module.prototype.require = function (modulePath) {
+  // Only redirect resolutions to non-relative and non-absolute modules
+  if (
+    ['/react/', '/react-dom/', '/react-query/'].some(d => {
+      try {
+        return require.resolve(modulePath).includes(d)
+      } catch (err) {
+        return false
+      }
+    })
+  ) {
+    try {
+      modulePath = resolveFrom(node_modules, modulePath)
+    } catch (err) {
+      //
+    }
+  }
+
+  return originalRequire.call(this, modulePath)
+}
+
+module.exports = {
+  webpack: config => {
+    config.resolve = {
+      ...config.resolve,
+      alias: {
+        ...config.resolve.alias,
+        react$: resolveFrom(path.resolve('node_modules'), 'react'),
+        'react-query$': resolveFrom(
+          path.resolve('node_modules'),
+          'react-query'
+        ),
+        'react-dom$': resolveFrom(path.resolve('node_modules'), 'react-dom'),
+      },
+    }
+    return config
+  },
+}

examples/optimistic-updates-typescript/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "basic",
+  "version": "1.0.0",
+  "main": "index.js",
+  "license": "MIT",
+  "dependencies": {
+    "axios": "^0.19.2",
+    "isomorphic-unfetch": "3.0.0",
+    "next": "9.2.2",
+    "react": "^17.0.1",
+    "react-dom": "^17.0.1",
+    "react-query": "^3.2.0-beta.32",
+    "react-query-devtools": "^3.0.0-beta.1",
+    "typescript": "^4.1.2"
+  },
+  "scripts": {
+    "dev": "next",
+    "start": "next start",
+    "build": "next build"
+  }
+}

examples/optimistic-updates-typescript/pages/api/data.js

@@ -0,0 +1,27 @@
+const items = []
+
+export default async (req, res) => {
+  await new Promise(r => setTimeout(r, 1000))
+
+  if (req.method === 'POST') {
+    const { text } = req.body
+
+    // sometimes it will fail, this will cause a regression on the UI
+
+    if (Math.random() > 0.7) {
+      res.status(500)
+      res.json({ message: 'Could not add item!' })
+      return
+    }
+
+    const newTodo = { id: Math.random().toString(), text: text.toUpperCase() }
+    items.push(newTodo)
+    res.json(newTodo)
+    return
+  } else {
+    res.json({
+      ts: Date.now(),
+      items,
+    })
+  }
+}

examples/optimistic-updates-typescript/pages/index.tsx

@@ -0,0 +1,145 @@
+import * as React from 'react'
+import axios, { AxiosError } from 'axios'
+
+import {
+  useQuery,
+  useQueryClient,
+  useMutation,
+  QueryClient,
+  QueryClientProvider,
+  UseQueryOptions,
+} from 'react-query'
+import { ReactQueryDevtools } from 'react-query-devtools'
+
+const client = new QueryClient()
+
+export default function App() {
+  return (
+    <QueryClientProvider client={client}>
+      <Example />
+      <TodoCounter />
+      <ReactQueryDevtools initialIsOpen />
+    </QueryClientProvider>
+  )
+}
+
+type Todos = {
+  items: readonly {
+    id: string
+    text: string
+  }[]
+  ts: number
+}
+
+async function fetchTodos(): Promise<Todos> {
+  const res = await axios.get('/api/data')
+  return res.data
+}
+
+function useTodos<TData = Todos>(
+  options?: UseQueryOptions<TData, AxiosError, Todos>
+) {
+  return useQuery('todos', fetchTodos, options)
+}
+
+function TodoCounter() {
+  // subscribe only to changes in the 'data' prop, which will be the
+  // amount of todos because of the select function
+  const counterQuery = useTodos({
+    select: data => data.items.length,
+    notifyOnChangeProps: ['data'],
+  })
+
+  React.useEffect(() => {
+    console.log('rendering counter')
+  })
+
+  return <div>TodoCounter: {counterQuery.data ?? 0}</div>
+}
+
+function Example() {
+  const queryClient = useQueryClient()
+  const [text, setText] = React.useState('')
+  const { isFetching, ...queryInfo } = useTodos()
+
+  const addTodoMutation = useMutation(
+    newTodo => axios.post('/api/data', { text: newTodo }),
+    {
+      // When mutate is called:
+      onMutate: async (newTodo: string) => {
+        setText('')
+        // Cancel any outgoing refetches (so they don't overwrite our optimistic update)
+        await queryClient.cancelQueries('todos')
+
+        // Snapshot the previous value
+        const previousTodos = queryClient.getQueryData<Todos>('todos')
+
+        // Optimistically update to the new value
+        if (previousTodos) {
+          queryClient.setQueryData<Todos>('todos', {
+            ...previousTodos,
+            items: [
+              ...previousTodos.items,
+              { id: Math.random().toString(), text: newTodo },
+            ],
+          })
+        }
+
+        return { previousTodos }
+      },
+      // If the mutation fails, use the context returned from onMutate to roll back
+      onError: (err, variables, context) => {
+        if (context?.previousTodos) {
+          queryClient.setQueryData<Todos>('todos', context.previousTodos)
+        }
+      },
+      // Always refetch after error or success:
+      onSettled: () => {
+        queryClient.invalidateQueries('todos')
+      },
+    }
+  )
+
+  return (
+    <div>
+      <p>
+        In this example, new items can be created using a mutation. The new item
+        will be optimistically added to the list in hopes that the server
+        accepts the item. If it does, the list is refetched with the true items
+        from the list. Every now and then, the mutation may fail though. When
+        that happens, the previous list of items is restored and the list is
+        again refetched from the server.
+      </p>
+      <form
+        onSubmit={e => {
+          e.preventDefault()
+          addTodoMutation.mutate(text)
+        }}
+      >
+        <input
+          type="text"
+          onChange={event => setText(event.target.value)}
+          value={text}
+        />
+        <button disabled={addTodoMutation.isLoading}>Create</button>
+      </form>
+      <br />
+      {queryInfo.isSuccess && (
+        <>
+          <div>
+            {/* The type of queryInfo.data will be narrowed because we check for isSuccess first */}
+            Updated At: {new Date(queryInfo.data.ts).toLocaleTimeString()}
+          </div>
+          <ul>
+            {queryInfo.data.items.map(todo => (
+              <li key={todo.id}>{todo.text}</li>
+            ))}
+          </ul>
+          {isFetching && <div>Updating in background...</div>}
+        </>
+      )}
+      {queryInfo.isLoading && 'Loading'}
+      {queryInfo.error?.message}
+    </div>
+  )
+}

examples/optimistic-updates-typescript/tsconfig.json

@@ -0,0 +1,26 @@
+{
+  "include": [
+    "./pages/**/*"
+  ],
+  "compilerOptions": {
+    "strict": true,
+    "esModuleInterop": true,
+    "lib": [
+      "dom",
+      "es2015"
+    ],
+    "jsx": "preserve",
+    "target": "es5",
+    "allowJs": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "noEmit": true,
+    "module": "esnext",
+    "moduleResolution": "node",
+    "resolveJsonModule": true,
+    "isolatedModules": true
+  },
+  "exclude": [
+    "node_modules"
+  ]
+}