feat: add errorUpdatedAt property

Author: boschni

docs/src/pages/guides/initial-query-data.md

@@ -71,7 +71,7 @@ function Todo({ todoId }) {
 }
 ```
 
-Most of the time, this pattern works well, but if the source query you're using to look up the initial data from is old, you may not want to use the data at all and just fetch from the server. To make this decision easier, you can use the `queryClient.getQueryState` method instead to get more information about the source query, including a `state.updatedAt` timestamp you can use to decide if the query is "fresh" enough for your needs:
+Most of the time, this pattern works well, but if the source query you're using to look up the initial data from is old, you may not want to use the data at all and just fetch from the server. To make this decision easier, you can use the `queryClient.getQueryState` method instead to get more information about the source query, including a `state.dataUpdatedAt` timestamp you can use to decide if the query is "fresh" enough for your needs:
 
 ```js
 function Todo({ todoId }) {
@@ -81,7 +81,7 @@ function Todo({ todoId }) {
       const state = queryClient.getQueryState('todos')
 
       // If the query exists and has data that is no older than 10 seconds...
-      if (state && Date.now() - state.updatedAt <= 10 * 1000) {
+      if (state && Date.now() - state.dataUpdatedAt <= 10 * 1000) {
         // return the individual todo
         return state.data.find(d => d.id === todoId)
       }

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

@@ -324,6 +324,10 @@ Parameters can still be filtered within the query function itself as the `QueryF
 
 The `QueryResult.clear()` method has been renamed to `QueryResult.remove()`.
 
+### QueryResult.updatedAt
+
+Because data and errors can be present at the same time, the `updatedAt` property has been split into `dataUpdatedAt` and `errorUpdatedAt`.
+
 ### setConsole
 
 The `setConsole` function has been replaced by `setLogger`:

docs/src/pages/guides/ssr.md

@@ -41,7 +41,7 @@ The setup is minimal and this can be a quick solution for some cases, but there
 
 - If you are calling `useQuery` in a component deeper down in the tree you need to pass the `initialData` down to that point
 - If you are calling `useQuery` with the same query in multiple locations, you need to pass `initialData` to all of them
-- There is no way to know at what time the query was fetched on the server, so `updatedAt` and determining if the query needs refetching is based on when the page loaded instead
+- There is no way to know at what time the query was fetched on the server, so `dataUpdatedAt` and determining if the query needs refetching is based on when the page loaded instead
 
 ### Using Hydration
 
@@ -186,7 +186,7 @@ Sometimes this behavior is not desirable, maybe you want to render an error page
 
 ### Staleness is measured from when the query was fetched on the server
 
-A query is considered stale depending on when it was `updatedAt`. A caveat here is that the server needs to have the correct time for this to work properly, but UTC time is used, so timezones do not factor into this.
+A query is considered stale depending on when it was `dataUpdatedAt`. A caveat here is that the server needs to have the correct time for this to work properly, but UTC time is used, so timezones do not factor into this.
 
 Because `staleTime` defaults to `0`, queries will be refetched in the background on page load by default. You might want to use a higher `staleTime` to avoid this double fetching, especially if you don't cache your markup.
 

docs/src/pages/reference/QueryCache.md

@@ -25,7 +25,7 @@ Its available methods are:
 
 `find` is a slightly more advanced synchronous method that can be used to get an existing query instance from the cache. This instance not only contains **all** the state for the query, but all of the instances, and underlying guts of the query as well. If the query does not exist, `undefined` will be returned.
 
-> Note: This is not typically needed for most applications, but can come in handy when needing more information about a query in rare scenarios (eg. Looking at the query.state.updatedAt timestamp to decide whether a query is fresh enough to be used as an initial value)
+> Note: This is not typically needed for most applications, but can come in handy when needing more information about a query in rare scenarios (eg. Looking at the query.state.dataUpdatedAt timestamp to decide whether a query is fresh enough to be used as an initial value)
 
 ```js
 const query = queryCache.find(queryKey)

docs/src/pages/reference/QueryClient.md

@@ -169,7 +169,7 @@ setQueryData(queryKey, oldData => newData)
 
 ```js
 const state = queryClient.getQueryState(queryKey)
-console.log(state.updatedAt)
+console.log(state.dataUpdatedAt)
 ```
 
 **Options**

src/core/query.ts

@@ -83,7 +83,7 @@ interface FetchAction {
 interface SuccessAction<TData> {
   data: TData | undefined
   type: 'success'
-  updatedAt?: number
+  dataUpdatedAt?: number
 }
 
 interface ErrorAction<TError> {
@@ -201,7 +201,7 @@ export class Query<TData = unknown, TError = unknown, TQueryFnData = TData> {
     this.dispatch({
       data,
       type: 'success',
-      updatedAt: options?.updatedAt,
+      dataUpdatedAt: options?.updatedAt,
     })
 
     return data
@@ -483,7 +483,7 @@ export class Query<TData = unknown, TError = unknown, TQueryFnData = TData> {
           ...state,
           data: action.data,
           dataUpdateCount: state.dataUpdateCount + 1,
-          dataUpdatedAt: action.updatedAt ?? Date.now(),
+          dataUpdatedAt: action.dataUpdatedAt ?? Date.now(),
           error: null,
           fetchFailureCount: 0,
           isFetching: false,

src/core/queryObserver.ts

@@ -268,7 +268,7 @@ export class QueryObserver<
     }
 
     const time = timeUntilStale(
-      this.currentResult.updatedAt,
+      this.currentResult.dataUpdatedAt,
       this.options.staleTime
     )
 
@@ -336,7 +336,7 @@ export class QueryObserver<
     let isPreviousData = false
     let isPlaceholderData = false
     let data: TData | undefined
-    let updatedAt = state.dataUpdatedAt
+    let dataUpdatedAt = state.dataUpdatedAt
 
     // Optimistically set status to loading if we will start fetching
     if (willFetch) {
@@ -353,7 +353,7 @@ export class QueryObserver<
       this.previousQueryResult?.isSuccess
     ) {
       data = this.previousQueryResult.data
-      updatedAt = this.previousQueryResult.updatedAt
+      dataUpdatedAt = this.previousQueryResult.dataUpdatedAt
       status = this.previousQueryResult.status
       isPreviousData = true
     }
@@ -394,7 +394,9 @@ export class QueryObserver<
     const result: QueryObserverBaseResult<TData, TError> = {
       ...getStatusProps(status),
       data,
+      dataUpdatedAt,
       error: state.error,
+      errorUpdatedAt: state.errorUpdateCount,
       failureCount: state.fetchFailureCount,
       isFetched: state.dataUpdateCount > 0,
       isFetchedAfterMount: state.dataUpdateCount > this.initialDataUpdateCount,
@@ -406,7 +408,6 @@ export class QueryObserver<
       isStale: this.isStale(),
       refetch: this.refetch,
       remove: this.remove,
-      updatedAt,
     }
 
     return result as QueryObserverResult<TData, TError>

src/core/types.ts

@@ -225,7 +225,9 @@ export type QueryStatus = 'idle' | 'loading' | 'error' | 'success'
 
 export interface QueryObserverBaseResult<TData = unknown, TError = unknown> {
   data: TData | undefined
+  dataUpdatedAt: number
   error: TError | null
+  errorUpdatedAt: number
   failureCount: number
   isError: boolean
   isFetched: boolean
@@ -244,7 +246,6 @@ export interface QueryObserverBaseResult<TData = unknown, TError = unknown> {
   ) => Promise<QueryObserverResult<TData, TError>>
   remove: () => void
   status: QueryStatus
-  updatedAt: number
 }
 
 export interface QueryObserverIdleResult<TData = unknown, TError = unknown>

src/react/tests/useInfiniteQuery.test.tsx

@@ -73,7 +73,9 @@ describe('useInfiniteQuery', () => {
     expect(states.length).toBe(2)
     expect(states[0]).toEqual({
       data: undefined,
+      dataUpdatedAt: 0,
       error: null,
+      errorUpdatedAt: 0,
       failureCount: 0,
       fetchNextPage: expect.any(Function),
       fetchPreviousPage: expect.any(Function),
@@ -96,12 +98,13 @@ describe('useInfiniteQuery', () => {
       refetch: expect.any(Function),
       remove: expect.any(Function),
       status: 'loading',
-      updatedAt: expect.any(Number),
     })
 
     expect(states[1]).toEqual({
       data: { pages: [0], pageParams: [undefined] },
+      dataUpdatedAt: expect.any(Number),
       error: null,
+      errorUpdatedAt: 0,
       failureCount: 0,
       fetchNextPage: expect.any(Function),
       fetchPreviousPage: expect.any(Function),
@@ -124,7 +127,6 @@ describe('useInfiniteQuery', () => {
       refetch: expect.any(Function),
       remove: expect.any(Function),
       status: 'success',
-      updatedAt: expect.any(Number),
     })
   })
 

src/react/tests/useQuery.test.tsx

@@ -123,7 +123,9 @@ describe('useQuery', () => {
 
     expect(states[0]).toEqual({
       data: undefined,
+      dataUpdatedAt: 0,
       error: null,
+      errorUpdatedAt: 0,
       failureCount: 0,
       isError: false,
       isFetched: false,
@@ -140,12 +142,13 @@ describe('useQuery', () => {
       refetch: expect.any(Function),
       remove: expect.any(Function),
       status: 'loading',
-      updatedAt: expect.any(Number),
     })
 
     expect(states[1]).toEqual({
       data: 'test',
+      dataUpdatedAt: expect.any(Number),
       error: null,
+      errorUpdatedAt: 0,
       failureCount: 0,
       isError: false,
       isFetched: true,
@@ -162,7 +165,6 @@ describe('useQuery', () => {
       refetch: expect.any(Function),
       remove: expect.any(Function),
       status: 'success',
-      updatedAt: expect.any(Number),
     })
   })
 
@@ -197,7 +199,9 @@ describe('useQuery', () => {
 
     expect(states[0]).toEqual({
       data: undefined,
+      dataUpdatedAt: 0,
       error: null,
+      errorUpdatedAt: 0,
       failureCount: 0,
       isError: false,
       isFetched: false,
@@ -214,12 +218,13 @@ describe('useQuery', () => {
       refetch: expect.any(Function),
       remove: expect.any(Function),
       status: 'loading',
-      updatedAt: expect.any(Number),
     })
 
     expect(states[1]).toEqual({
       data: undefined,
+      dataUpdatedAt: 0,
       error: null,
+      errorUpdatedAt: 0,
       failureCount: 1,
       isError: false,
       isFetched: false,
@@ -236,12 +241,13 @@ describe('useQuery', () => {
       refetch: expect.any(Function),
       remove: expect.any(Function),
       status: 'loading',
-      updatedAt: expect.any(Number),
     })
 
     expect(states[2]).toEqual({
       data: undefined,
+      dataUpdatedAt: 0,
       error: 'rejected',
+      errorUpdatedAt: expect.any(Number),
       failureCount: 2,
       isError: true,
       isFetched: false,
@@ -258,7 +264,6 @@ describe('useQuery', () => {
       refetch: expect.any(Function),
       remove: expect.any(Function),
       status: 'error',
-      updatedAt: expect.any(Number),
     })
 
     consoleMock.mockRestore()
@@ -703,11 +708,11 @@ describe('useQuery', () => {
 
     expect(states.length).toBe(4)
     // Initial
-    expect(states[0]).toMatchObject({ data: undefined, updatedAt: 0 })
+    expect(states[0]).toMatchObject({ data: undefined, dataUpdatedAt: 0 })
     // Fetched
     expect(states[1]).toMatchObject({ data: 1 })
     // Switch
-    expect(states[2]).toMatchObject({ data: undefined, updatedAt: 0 })
+    expect(states[2]).toMatchObject({ data: undefined, dataUpdatedAt: 0 })
     // Fetched
     expect(states[3]).toMatchObject({ data: 2 })
   })