@tanstack/react-query-devtools 4.26.1 → 4.27.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/react-query-devtools",
-  "version": "4.26.1",
+  "version": "4.27.0",
   "description": "Developer tools to interact with and visualize the TanStack/react-query cache",
   "author": "tannerlinsley",
   "license": "MIT",
@@ -46,7 +46,7 @@
     "react-dom": "^18.2.0",
     "react-dom-17": "npm:react-dom@^17.0.2",
     "react-error-boundary": "^3.1.4",
-    "@tanstack/react-query": "4.26.1"
+    "@tanstack/react-query": "4.27.0"
   },
   "dependencies": {
     "@tanstack/match-sorter-utils": "^8.7.0",
@@ -56,7 +56,7 @@
   "peerDependencies": {
     "react": "^16.8.0 || ^17.0.0 || ^18.0.0",
     "react-dom": "^16.8.0 || ^17.0.0 || ^18.0.0",
-    "@tanstack/react-query": "4.26.1"
+    "@tanstack/react-query": "4.27.0"
   },
   "scripts": {
     "clean": "rimraf ./build",

package/src/__tests__/devtools.test.tsx

@@ -11,6 +11,7 @@ import {
   sleep,
   createQueryClient,
 } from './utils'
+import UserEvent from '@testing-library/user-event'
 
 // TODO: This should be removed with the types for react-error-boundary get updated.
 declare module 'react-error-boundary' {
@@ -19,6 +20,13 @@ declare module 'react-error-boundary' {
   }
 }
 
+class CustomError extends Error {
+  constructor(message: string) {
+    super(message)
+    this.name = 'CustomError'
+  }
+}
+
 Object.defineProperty(window, 'matchMedia', {
   writable: true,
   value: jest.fn().mockImplementation((query: string) => ({
@@ -915,4 +923,135 @@ describe('ReactQueryDevtools', () => {
     fireEvent.click(screen.getByRole('button', { name: /^close$/i }))
     expect(parentElement).toHaveStyle(parentPaddings)
   })
+
+  it('should simulate loading state', async () => {
+    const { queryClient } = createQueryClient()
+    let count = 0
+    function App() {
+      const { data, fetchStatus } = useQuery(['key'], () => {
+        count++
+        return Promise.resolve('test')
+      })
+
+      return (
+        <div>
+          <h1>
+            {data ?? 'No data'}, {fetchStatus}
+          </h1>
+        </div>
+      )
+    }
+
+    renderWithClient(queryClient, <App />, {
+      initialIsOpen: true,
+    })
+
+    await screen.findByRole('heading', { name: /test/i })
+
+    const loadingButton = await screen.findByRole('button', {
+      name: 'Trigger loading',
+    })
+    fireEvent.click(loadingButton)
+
+    await waitFor(() => {
+      expect(screen.getByText('Restore loading')).toBeInTheDocument()
+    })
+
+    await waitFor(() => {
+      expect(screen.getByText('No data, fetching')).toBeInTheDocument()
+    })
+
+    fireEvent.click(screen.getByRole('button', { name: /restore loading/i }))
+
+    await waitFor(() => {
+      expect(screen.getByText('test, idle')).toBeInTheDocument()
+    })
+
+    expect(count).toBe(2)
+  })
+
+  it('should simulate error state', async () => {
+    const { queryClient } = createQueryClient()
+    function App() {
+      const { status, error } = useQuery(['key'], () => {
+        return Promise.resolve('test')
+      })
+
+      return (
+        <div>
+          <h1>
+            {!!error ? 'Some error' : 'No error'}, {status}
+          </h1>
+        </div>
+      )
+    }
+
+    renderWithClient(queryClient, <App />, {
+      initialIsOpen: true,
+    })
+
+    const errorButton = await screen.findByRole('button', {
+      name: 'Trigger error',
+    })
+    fireEvent.click(errorButton)
+
+    await waitFor(() => {
+      expect(screen.getByText('Restore error')).toBeInTheDocument()
+    })
+
+    await waitFor(() => {
+      expect(screen.getByText('Some error, error')).toBeInTheDocument()
+    })
+
+    fireEvent.click(screen.getByRole('button', { name: /Restore error/i }))
+
+    await waitFor(() => {
+      expect(screen.getByText('No error, success')).toBeInTheDocument()
+    })
+  })
+
+  it('should can simulate a specific error', async () => {
+    const { queryClient } = createQueryClient()
+
+    function App() {
+      const { status, error } = useQuery(['key'], () => {
+        return Promise.resolve('test')
+      })
+
+      return (
+        <div data-testid="test">
+          <h1>
+            {error instanceof CustomError
+              ? error.message.toString()
+              : 'No error'}
+            , {status}
+          </h1>
+        </div>
+      )
+    }
+
+    renderWithClient(queryClient, <App />, {
+      initialIsOpen: true,
+      errorTypes: [
+        {
+          name: 'error1',
+          initializer: () => new CustomError('error1'),
+        },
+      ],
+    })
+
+    const errorOption = await screen.findByLabelText('Trigger error:')
+
+    UserEvent.selectOptions(errorOption, 'error1')
+
+    await waitFor(() => {
+      expect(screen.getByText('error1, error')).toBeInTheDocument()
+    })
+
+    fireEvent.click(screen.getByRole('button', { name: /Restore error/i }))
+
+    await waitFor(() => {
+      expect(screen.getByText('No error, success')).toBeInTheDocument()
+    })
+  })
 })

package/src/devtools.tsx

@@ -6,6 +6,7 @@ import type {
   QueryClient,
   QueryKey as QueryKeyType,
   ContextOptions,
+  Query,
 } from '@tanstack/react-query'
 import {
   useQueryClient,
@@ -41,6 +42,19 @@ import { ThemeProvider, defaultTheme as theme } from './theme'
 import { getQueryStatusLabel, getQueryStatusColor } from './utils'
 import Explorer from './Explorer'
 import Logo from './Logo'
+import { useMemo } from 'react'
+
+export interface DevToolsErrorType {
+  /**
+   * The name of the error.
+   */
+  name: string
+  /**
+   * How the error is initialized. Whatever it returns MUST implement toString() so
+   * we can check against the current error.
+   */
+  initializer: (query: Query) => { toString(): string }
+}
 
 export interface DevtoolsOptions extends ContextOptions {
   /**
@@ -79,6 +93,10 @@ export interface DevtoolsOptions extends ContextOptions {
    * nonce for style element for CSP
    */
   styleNonce?: string
+  /**
+   * Use this so you can define custom errors that can be shown in the devtools.
+   */
+  errorTypes?: DevToolsErrorType[]
 }
 
 interface DevtoolsPanelOptions extends ContextOptions {
@@ -123,6 +141,10 @@ interface DevtoolsPanelOptions extends ContextOptions {
    * Use this to add props to the close button. For example, you can add className, style (merge and override default style), onClick (extend default handler), etc.
    */
   closeButtonProps?: React.ComponentPropsWithoutRef<'button'>
+  /**
+   * Use this so you can define custom errors that can be shown in the devtools.
+   */
+  errorTypes?: DevToolsErrorType[]
 }
 
 export function ReactQueryDevtools({
@@ -135,6 +157,7 @@ export function ReactQueryDevtools({
   context,
   styleNonce,
   panelPosition: initialPanelPosition = 'bottom',
+  errorTypes = [],
 }: DevtoolsOptions): React.ReactElement | null {
   const rootRef = React.useRef<HTMLDivElement>(null)
   const panelRef = React.useRef<HTMLDivElement>(null)
@@ -343,6 +366,7 @@ export function ReactQueryDevtools({
           isOpen={isResolvedOpen}
           setIsOpen={setIsOpen}
           onDragStart={(e) => handleDragStart(panelRef.current, e)}
+          errorTypes={errorTypes}
         />
       </ThemeProvider>
       {!isResolvedOpen ? (
@@ -433,6 +457,7 @@ export const ReactQueryDevtoolsPanel = React.forwardRef<
     showCloseButton,
     position,
     closeButtonProps = {},
+    errorTypes = [],
     ...panelProps
   } = props
 
@@ -605,6 +630,8 @@ export const ReactQueryDevtoolsPanel = React.forwardRef<
                   style={{
                     display: 'flex',
                     alignItems: 'center',
+                    flexWrap: 'wrap',
+                    gap: '0.5em',
                   }}
                 >
                   <Input
@@ -617,7 +644,6 @@ export const ReactQueryDevtoolsPanel = React.forwardRef<
                     }}
                     style={{
                       flex: '1',
-                      marginRight: '.5em',
                       width: '100%',
                     }}
                   />
@@ -738,6 +764,7 @@ export const ReactQueryDevtoolsPanel = React.forwardRef<
             activeQueryHash={activeQueryHash}
             queryCache={queryCache}
             queryClient={queryClient}
+            errorTypes={errorTypes}
           />
         ) : null}
 
@@ -773,10 +800,12 @@ const ActiveQuery = ({
   queryCache,
   activeQueryHash,
   queryClient,
+  errorTypes,
 }: {
   queryCache: QueryCache
   activeQueryHash: string
   queryClient: QueryClient
+  errorTypes: DevToolsErrorType[]
 }) => {
   const activeQuery = useSubscribeToQueryCache(queryCache, () =>
     queryCache.getAll().find((query) => query.queryHash === activeQueryHash),
@@ -810,10 +839,46 @@ const ActiveQuery = ({
     promise?.catch(noop)
   }
 
+  const currentErrorTypeName = useMemo(() => {
+    if (activeQuery && activeQueryState?.error) {
+      const errorType = errorTypes.find(
+        (type) =>
+          type.initializer(activeQuery).toString() ===
+          activeQueryState.error?.toString(),
+      )
+      return errorType?.name
+    }
+    return undefined
+  }, [activeQuery, activeQueryState?.error, errorTypes])
+
   if (!activeQuery || !activeQueryState) {
     return null
   }
 
+  const triggerError = (errorType?: DevToolsErrorType) => {
+    const error =
+      errorType?.initializer(activeQuery) ??
+      new Error('Unknown error from devtools')
+
+    const __previousQueryOptions = activeQuery.options
+
+    activeQuery.setState({
+      status: 'error',
+      error,
+      fetchMeta: {
+        ...activeQuery.state.fetchMeta,
+        __previousQueryOptions,
+      },
+    })
+  }
+
+  const restoreQueryAfterLoadingOrError = () => {
+    activeQuery.fetch(activeQuery.state.fetchMeta.__previousQueryOptions, {
+      // Make sure this fetch will cancel the previous one
+      cancelRefetch: true,
+    })
+  }
+
   return (
     <ActiveQueryPanel>
       <div
@@ -910,6 +975,10 @@ const ActiveQuery = ({
       <div
         style={{
           padding: '0.5em',
+          display: 'flex',
+          flexWrap: 'wrap',
+          gap: '0.5em',
+          alignItems: 'flex-end',
         }}
       >
         <Button
@@ -949,7 +1018,80 @@ const ActiveQuery = ({
           }}
         >
           Remove
-        </Button>
+        </Button>{' '}
+        <Button
+          type="button"
+          onClick={() => {
+            if (activeQuery.state.data === undefined) {
+              restoreQueryAfterLoadingOrError()
+            } else {
+              const __previousQueryOptions = activeQuery.options
+              // Trigger a fetch in order to trigger suspense as well.
+              activeQuery.fetch({
+                ...__previousQueryOptions,
+                queryFn: () => {
+                  return new Promise(() => {
+                    // Never resolve
+                  })
+                },
+                cacheTime: -1,
+              })
+              activeQuery.setState({
+                data: undefined,
+                status: 'loading',
+                fetchMeta: {
+                  ...activeQuery.state.fetchMeta,
+                  __previousQueryOptions,
+                },
+              })
+            }
+          }}
+          style={{
+            background: theme.paused,
+          }}
+        >
+          {activeQuery.state.status === 'loading' ? 'Restore' : 'Trigger'}{' '}
+          loading
+        </Button>{' '}
+        {errorTypes.length === 0 || activeQuery.state.status === 'error' ? (
+          <Button
+            type="button"
+            onClick={() => {
+              if (!activeQuery.state.error) {
+                triggerError()
+              } else {
+                queryClient.resetQueries(activeQuery)
+              }
+            }}
+            style={{
+              background: theme.danger,
+            }}
+          >
+            {activeQuery.state.status === 'error' ? 'Restore' : 'Trigger'} error
+          </Button>
+        ) : (
+          <label>
+            Trigger error:
+            <Select
+              value={currentErrorTypeName ?? ''}
+              style={{ marginInlineStart: '.5em' }}
+              onChange={(e) => {
+                const errorType = errorTypes.find(
+                  (t) => t.name === e.target.value,
+                )
+
+                triggerError(errorType)
+              }}
+            >
+              <option key="" value="" />
+              {errorTypes.map((errorType) => (
+                <option key={errorType.name} value={errorType.name}>
+                  {errorType.name}
+                </option>
+              ))}
+            </Select>
+          </label>
+        )}
       </div>
       <div
         style={{

package/src/styledComponents.ts

@@ -50,7 +50,9 @@ export const Button = styled('button', (props, theme) => ({
 }))
 
 export const QueryKeys = styled('span', {
-  display: 'inline-block',
+  display: 'flex',
+  flexWrap: 'wrap',
+  gap: '0.5em',
   fontSize: '0.9em',
 })