feat: initial v3 changes

Author: boschni

.github/workflows/test-and-publish.yml

@@ -38,7 +38,7 @@ jobs:
           registry-url: https://registry.npmjs.org/
       - name: Install dependencies
         uses: bahmutov/npm-install@v1
-      - run: yarn build && yarn build:types
+      - run: yarn build
       - run: npx semantic-release@17
         env:
           NODE_AUTH_TOKEN: ${{secrets.npm_token}}

.gitignore

@@ -5,13 +5,15 @@
 node_modules
 
 # builds
+types
 build
 dist
 lib
 es
 artifacts
 .rpt2_cache
 coverage
+*.tgz
 
 # misc
 .DS_Store
@@ -31,5 +33,3 @@ stats-hydration.json
 stats-react.json
 stats.html
 .vscode/settings.json
-
-types

core/package.json

@@ -0,0 +1,6 @@
+{
+  "internal": true,
+  "main": "../lib/core/index.js",
+  "module": "../es/core/index.js",
+  "types": "../types/core/index.d.ts"
+}

docs/src/pages/docs/api.md

@@ -28,6 +28,7 @@ Feature/Capability Key:
 | Paginated Queries                            | ✅                                     | ✅                         | ✅                                    |
 | Infinite Queries                             | ✅                                     | ✅                         | ✅                                    |
 | Lagged / "Lazy" Queries<sup>1</sup>          | ✅                                     | 🛑                         | 🛑                                    |
+| Selectors                                    | ✅                                     | 🛑                         | ✅                                    |
 | Initial Data                                 | ✅                                     | ✅                         | ✅                                    |
 | Scroll Recovery                              | ✅                                     | ✅                         | ✅                                    |
 | Cache Manipulation                           | ✅                                     | ✅                         | ✅                                    |

docs/src/pages/docs/comparison.md

@@ -0,0 +1,291 @@
+---
+id: migrating-to-react-query-3
+title: Migrating to React Query 3
+---
+
+## V3 migration
+
+This article explains how to migrate your application to React Query 3.
+
+### QueryClient
+
+The `QueryCache` has been split into a `QueryClient` and a `QueryCache`.
+The `QueryCache` contains all cached queries and the `QueryClient` can be used to interact with a cache.
+
+This has some benefits:
+
+- Allows for different type of caches.
+- Multiple clients with different configurations can use the same cache.
+- Clients can be used to track queries, which can be used for shared caches on SSR.
+- The client API is more focused towards general usage.
+- Easier to test the individual components.
+
+Use the `QueryClientProvider` component to connect a `QueryClient` to your application:
+
+```js
+import { QueryClient, QueryClientProvider, QueryCache } from 'react-query'
+
+const cache = new QueryCache()
+const client = new QueryClient({ cache })
+
+function App() {
+  return <QueryClientProvider client={client}>...</QueryClientProvider>
+}
+```
+
+### useQueryCache()
+
+The `useQueryCache()` hook has been replaced by the `useQueryClient()` hook:
+
+```js
+import { useCallback } from 'react'
+import { useQueryClient } from 'react-query'
+
+function Todo() {
+  const client = useQueryClient()
+
+  const onClickButton = useCallback(() => {
+    client.refetchQueries('posts')
+  }, [client])
+
+  return <button onClick={onClickButton}>Refetch</button>
+}
+```
+
+### ReactQueryConfigProvider
+
+The `ReactQueryConfigProvider` component has been removed. Default options for queries and mutations can now be specified in `QueryClient`:
+
+```js
+const client = new QueryClient({
+  cache,
+  defaultOptions: {
+    queries: {
+      staleTime: Infinity,
+    },
+  },
+})
+```
+
+### usePaginatedQuery()
+
+The `usePaginatedQuery()` hook has been replaced by the `keepPreviousData` option on `useQuery`:
+
+```js
+import { useQuery } from 'react-query'
+
+function Page({ page }) {
+  const { data } = useQuery(['page', page], fetchPage, {
+    keepPreviousData: true,
+  })
+}
+```
+
+### Query object syntax
+
+The object syntax has been collapsed:
+
+```js
+// Old:
+useQuery({
+  queryKey: 'posts',
+  queryFn: fetchPosts,
+  config: { staleTime: Infinity },
+})
+
+// New:
+useQuery({
+  queryKey: 'posts',
+  queryFn: fetchPosts,
+  staleTime: Infinity,
+})
+```
+
+### queryCache.invalidateQueries()
+
+The `client.invalidateQueries()` method will now only invalidate queries.
+All matched queries will be marked invalid and refetched on window focus, reconnect or mounting of components.
+Use `client.refetchQueries()` to refetch queries immediately.
+
+### queryCache.refetchQueries()
+
+The `client.refetchQueries()` method can be used to refetch queries like the `refetch()` method.
+By default it will only refetch active queries, but an `inactive` flag can be set to also refetch inactive queries.
+
+```js
+// Refetch all active queries:
+client.refetchQueries()
+
+// Refetch all active and inactive queries:
+client.refetchQueries({ active: true, inactive: true })
+
+// Fetch active queries matching a query key:
+client.refetchQueries('posts')
+
+// Refetch active and inactive queries:
+client.refetchQueries('posts', { active: true, inactive: true })
+
+// Only fetch inactive queries:
+client.refetchQueries('posts', { active: false, inactive: true })
+```
+
+The same filters can be used in the `client.cancelQueries()`, `client.invalidateQueries()` and `client.removeQueries()` methods but these methods will include all queries by default.
+
+### queryCache.prefetchQuery()
+
+The `client.prefetchQuery()` method should now only be used for prefetching scenarios where the result is not relevant.
+
+Use the `client.fetchQueryData()` method to get the query data or error:
+
+```js
+// Prefetch a query:
+await client.prefetchQuery('posts', fetchPosts)
+
+// Fetch a query:
+try {
+  const data = await client.fetchQueryData('posts', fetchPosts)
+} catch (error) {
+  // Error handling
+}
+```
+
+### ReactQueryCacheProvider
+
+The `ReactQueryCacheProvider` component has been replaced by the `QueryClientProvider` component.
+
+### makeQueryCache()
+
+The `makeQueryCache()` function has replaced by `new QueryCache()`.
+
+### ReactQueryErrorResetBoundary
+
+The `ReactQueryErrorResetBoundary` component has been renamed to `QueryErrorResetBoundary`.
+
+### queryCache.resetErrorBoundaries()
+
+The `queryCache.resetErrorBoundaries()` method has been replaced by the `QueryErrorResetBoundary` component.
+
+### queryCache.getQuery()
+
+The `queryCache.getQuery()` method has been replaced by `cache.find()`.
+
+### queryCache.getQueries()
+
+The `queryCache.getQueries()` method has been replaced by `cache.findAll()`.
+
+### queryCache.isFetching
+
+The `queryCache.isFetching` property has been replaced by `client.isFetching()`.
+
+### QueryOptions.initialStale
+
+The `initialStale` query option has been removed and initial data is now treated as regular data.
+Which means that if `initialData` is provided, the query will refetch on mount by default.
+If you do not want to refetch immediately, you can define a `staleTime`.
+
+### QueryOptions.forceFetchOnMount
+
+The `forceFetchOnMount` query option has been replaced by `refetchOnMount: 'always'`.
+
+### QueryOptions.refetchOnMount
+
+When `refetchOnMount` was set to `false` any additional components were prevented from refetching on mount.
+In version 3 only the component where the option has been set will not refetch on mount.
+
+### QueryResult.clear()
+
+The `QueryResult.clear()` method has been renamed to `QueryResult.remove()`.
+
+### New features
+
+Some new features have also been added besides the API changes, performance improvements and file size reduction.
+
+#### Selectors
+
+The `useQuery` and `useInfiniteQuery` hooks now have a `select` option to select or transform parts of the query result.
+
+```js
+import { useQuery } from 'react-query'
+
+function User() {
+  const { data } = useQuery('user', fetchUser, {
+    select: user => user.username,
+  })
+  return <div>Username: {data}</div>
+}
+```
+
+Set the `notifyOnStatusChange` option to `false` to only re-render when the selected data changes.
+
+#### useQueries()
+
+The `useQueries()` hook can be used to fetch a variable number of queries:
+
+```js
+import { useQueries } from 'react-query'
+
+function Overview() {
+  const results = useQueries([
+    { queryKey: ['post', 1], queryFn: fetchPost },
+    { queryKey: ['post', 2], queryFn: fetchPost },
+  ])
+  return (
+    <ul>
+      {results.map(({ data }) => data && <li key={data.id}>{data.title})</li>)}
+    </ul>
+  )
+}
+```
+
+#### client.watchQuery()
+
+The `client.watchQuery()` method can be used to create and/or watch a query:
+
+```js
+const observer = client.watchQuery('posts')
+
+observer.subscribe(result => {
+  console.log(result)
+  observer.unsubscribe()
+})
+```
+
+#### client.watchQueries()
+
+The `client.watchQueries()` method can be used to create and/or watch multiple queries:
+
+```js
+const observer = client.watchQueries([
+  { queryKey: ['post', 1], queryFn: fetchPost },
+  { queryKey: ['post', 2], queryFn: fetchPost },
+])
+
+observer.subscribe(result => {
+  console.log(result)
+  observer.unsubscribe()
+})
+```
+
+#### React Native error screens
+
+To prevent showing error screens in React Native when a query fails it was necessary to manually change the Console:
+
+```js
+import { setConsole } from 'react-query'
+
+setConsole({
+  log: console.log,
+  warn: console.warn,
+  error: console.warn,
+})
+```
+
+In version 3 this is done automatically when React Query is used in React Native.
+
+#### Core separation
+
+The core of React Query is now fully separated from React, which means it can also be used standalone or in other frameworks. Use the `react-query/core` entrypoint to only import the core functionality:
+
+```js
+import { QueryClient } from 'react-query/core'
+```

docs/src/pages/docs/guides/migrating-to-react-query-3.md

@@ -257,3 +257,33 @@ function GlobalLoadingIndicator() {
   ) : null
 }
 ```
+
+# Query Filters
+
+Some methods within React Query accept a `QueryFilters` object. A query filter is an object with certain conditions to match a query with:
+
+```js
+await client.refetchQueries({ active: true, inactive: true })
+await client.refetchQueries('posts', { active: true, inactive: true })
+```
+
+A query filter object supports the following properties:
+
+- `exact?: boolean`
+  - If you don't want to search queries inclusively by query key, you can pass the `exact: true` option to return only the query with the exact query key you have passed.
+- `active?: boolean`
+  - When set to `true` it will match active queries.
+  - When set to `false` it will match inactive queries.
+- `inactive?: boolean`
+  - When set to `true` it will match active queries.
+  - When set to `false` it will match inactive queries.
+- `stale?: boolean`
+  - When set to `true` it will match stale queries.
+  - When set to `false` it will not match stale queries.
+- `fresh?: boolean`
+  - When set to `true` it will match fresh queries.
+  - When set to `false` it will not match fresh queries.
+- `predicate?: (query: Query) => boolean`
+  - This predicate function will be called for every single query in the cache and be expected to return truthy for queries that are `found`.
+- `queryKey?: QueryKey`
+  - Set this property to define a query key to match on.