feat: add notify flags for controlling re-renders

Author: boschni

docs/src/pages/docs/api.md

@@ -33,6 +33,9 @@ const {
   queryFnParamsFilter,
   refetchOnMount,
   isDataEqual,
+  notifyOnFailureCountChange,
+  notifyOnStaleChange,
+  notifyOnStatusChange,
   onError,
   onSuccess,
   onSettled,
@@ -90,6 +93,18 @@ const queryInfo = useQuery({
 - `refetchOnWindowFocus: Boolean`
   - Optional
   - Set this to `true` or `false` to enable/disable automatic refetching on window focus for this query.
+- `notifyOnFailureCountChange: Boolean`
+  - Optional
+  - Defaults to `true`
+  - Whether components should re-render when a query failure count changes.
+- `notifyOnStaleChange: Boolean`
+  - Optional
+  - Defaults to `true`
+  - Whether components should re-render when a query becomes stale.
+- `notifyOnStatusChange: Boolean`
+  - Optional
+  - Defaults to `true`
+  - Whether components should re-render when a query status changes. This includes the `isFetching` and `isFetchingMore` states.
 - `onSuccess: Function(data) => data`
   - Optional
   - This function will fire any time the query successfully fetches new data.

src/core/config.ts

@@ -1,4 +1,4 @@
-import { stableStringify, identity, deepEqual } from './utils'
+import { stableStringify, deepEqual } from './utils'
 import {
   ArrayQueryKey,
   QueryKey,
@@ -30,26 +30,19 @@ export const defaultQueryKeySerializerFn: QueryKeySerializerFunction = (
 }
 
 export const DEFAULT_CONFIG: ReactQueryConfig = {
-  shared: {
-    suspense: false,
-  },
   queries: {
     queryKeySerializerFn: defaultQueryKeySerializerFn,
     enabled: true,
     retry: 3,
     retryDelay: attemptIndex => Math.min(1000 * 2 ** attemptIndex, 30000),
     staleTime: 0,
     cacheTime: 5 * 60 * 1000,
+    notifyOnFailureCountChange: true,
+    notifyOnStaleChange: true,
+    notifyOnStatusChange: true,
     refetchOnWindowFocus: true,
-    refetchInterval: false,
-    queryFnParamsFilter: identity,
     refetchOnMount: true,
     isDataEqual: deepEqual,
-    useErrorBoundary: false,
-  },
-  mutations: {
-    throwOnError: false,
-    useErrorBoundary: false,
   },
 }
 

src/core/query.ts

@@ -1,7 +1,7 @@
 import {
+  isCancelable,
   isServer,
   functionalUpdate,
-  cancelledError,
   isDocumentVisible,
   noop,
   Console,
@@ -104,6 +104,8 @@ export type Action<TResult, TError> =
   | SetStateAction<TResult, TError>
   | SuccessAction<TResult>
 
+class CancelledError extends Error {}
+
 // CLASS
 
 export class Query<TResult, TError> {
@@ -122,7 +124,7 @@ export class Query<TResult, TError> {
   private retryTimeout?: number
   private staleTimeout?: number
   private cancelPromises?: () => void
-  private cancelled?: typeof cancelledError | null
+  private cancelled?: boolean
   private notifyGlobalListeners: (query: Query<TResult, TError>) => void
 
   constructor(init: QueryInitConfig<TResult, TError>) {
@@ -157,12 +159,13 @@ export class Query<TResult, TError> {
   }
 
   private dispatch(action: Action<TResult, TError>): void {
-    const newState = queryReducer(this.state, action)
+    const prevState = this.state
+    const newState = queryReducer(prevState, action)
 
     // Only update state if something has changed
-    if (!shallowEqual(this.state, newState)) {
+    if (!shallowEqual(prevState, newState)) {
       this.state = newState
-      this.instances.forEach(d => d.onStateUpdate(newState, action))
+      this.instances.forEach(d => d.onStateUpdate(newState, prevState, action))
       this.notifyGlobalListeners(this)
     }
   }
@@ -236,11 +239,15 @@ export class Query<TResult, TError> {
     this.clearCacheTimeout()
 
     // Mark the query as not cancelled
-    this.cancelled = null
+    this.cancelled = false
+  }
+
+  canCancel(): boolean {
+    return !this.cancelled && Boolean(this.cancelPromises)
   }
 
   cancel(): void {
-    this.cancelled = cancelledError
+    this.cancelled = true
 
     if (this.cancelPromises) {
       this.cancelPromises()
@@ -322,21 +329,32 @@ export class Query<TResult, TError> {
     args: ArrayQueryKey
   ): Promise<TResult> {
     try {
+      const filter = this.config.queryFnParamsFilter
+      const params = filter ? filter(args) : args
+
       // Perform the query
-      const promiseOrValue = fn(...this.config.queryFnParamsFilter!(args))
+      const promiseOrValue = fn(...params)
 
-      this.cancelPromises = () => (promiseOrValue as any)?.cancel?.()
+      if (isCancelable(promiseOrValue)) {
+        this.cancelPromises = () => promiseOrValue.cancel()
+      }
 
       const data = await promiseOrValue
       delete this.shouldContinueRetryOnFocus
 
       delete this.cancelPromises
-      if (this.cancelled) throw this.cancelled
+
+      if (this.cancelled) {
+        throw new CancelledError()
+      }
 
       return data
     } catch (error) {
       delete this.cancelPromises
-      if (this.cancelled) throw this.cancelled
+
+      if (this.cancelled) {
+        throw new CancelledError()
+      }
 
       // Do we need to retry the request?
       if (
@@ -368,14 +386,23 @@ export class Query<TResult, TError> {
         return await new Promise((resolve, reject) => {
           // Keep track of the retry timeout
           this.retryTimeout = setTimeout(async () => {
-            if (this.cancelled) return reject(this.cancelled)
+            if (this.cancelled) {
+              return reject(new CancelledError())
+            }
 
             try {
               const data = await this.tryFetchData(fn, args)
-              if (this.cancelled) return reject(this.cancelled)
+
+              if (this.cancelled) {
+                return reject(new CancelledError())
+              }
+
               resolve(data)
             } catch (error) {
-              if (this.cancelled) return reject(this.cancelled)
+              if (this.cancelled) {
+                return reject(new CancelledError())
+              }
+
               reject(error)
             }
           }, delay)
@@ -499,7 +526,7 @@ export class Query<TResult, TError> {
 
     this.promise = (async () => {
       // If there are any retries pending for this query, kill them
-      this.cancelled = null
+      this.cancelled = false
 
       try {
         // Set up the query refreshing state
@@ -514,15 +541,17 @@ export class Query<TResult, TError> {
 
         return data
       } catch (error) {
+        const cancelled = error instanceof CancelledError
+
         this.dispatch({
           type: ActionType.Error,
-          cancelled: error === this.cancelled,
+          cancelled,
           error,
         })
 
         delete this.promise
 
-        if (error !== this.cancelled) {
+        if (!cancelled) {
           throw error
         }
 
@@ -556,11 +585,31 @@ function getDefaultState<TResult, TError>(
 
   const hasInitialData = typeof initialData !== 'undefined'
 
-  const isStale =
-    !config.enabled ||
-    (typeof config.initialStale === 'function'
-      ? config.initialStale()
-      : config.initialStale ?? !hasInitialData)
+  // A query is stale by default
+  let isStale = true
+
+  if (hasInitialData) {
+    // When initial data is provided, the query is not stale by default
+    isStale = false
+
+    // Mark the query as stale if initialStale is set to `true`
+    if (config.initialStale === true) {
+      isStale = true
+    }
+
+    // Mark the query as stale if initialStale is set to a function which returns `true`
+    if (
+      typeof config.initialStale === 'function' &&
+      config.initialStale() === true
+    ) {
+      isStale = true
+    }
+  }
+
+  // Always mark the query as stale when it is not enabled
+  if (!config.enabled) {
+    isStale = true
+  }
 
   const initialStatus = hasInitialData
     ? QueryStatus.Success

src/core/queryInstance.ts

@@ -1,6 +1,6 @@
 import { uid, isServer, isDocumentVisible, Console } from './utils'
 import { Query, QueryState, Action, ActionType } from './query'
-import { BaseQueryConfig } from './types'
+import { BaseQueryInstanceConfig } from './types'
 
 // TYPES
 
@@ -12,20 +12,20 @@ export type OnStateUpdateFunction<TResult, TError> = (
 
 export class QueryInstance<TResult, TError> {
   id: number
-  config: BaseQueryConfig<TResult, TError>
+  config: BaseQueryInstanceConfig<TResult, TError>
 
   private query: Query<TResult, TError>
   private refetchIntervalId?: number
   private stateUpdateListener?: OnStateUpdateFunction<TResult, TError>
 
   constructor(
     query: Query<TResult, TError>,
-    onStateUpdate?: OnStateUpdateFunction<TResult, TError>
+    stateUpdateListener?: OnStateUpdateFunction<TResult, TError>
   ) {
     this.id = uid()
-    this.stateUpdateListener = onStateUpdate
     this.query = query
     this.config = {}
+    this.stateUpdateListener = stateUpdateListener
   }
 
   clearInterval(): void {
@@ -35,7 +35,7 @@ export class QueryInstance<TResult, TError> {
     }
   }
 
-  updateConfig(config: BaseQueryConfig<TResult, TError>): void {
+  updateConfig(config: BaseQueryInstanceConfig<TResult, TError>): void {
     const oldConfig = this.config
 
     // Update the config
@@ -93,7 +93,11 @@ export class QueryInstance<TResult, TError> {
 
     if (!this.query.instances.length) {
       this.clearInterval()
-      this.query.cancel()
+
+      // Only cancel the query if the transport layer supports cancellation
+      if (this.query.canCancel()) {
+        this.query.cancel()
+      }
 
       if (!preventGC && !isServer) {
         // Schedule garbage collection
@@ -104,18 +108,57 @@ export class QueryInstance<TResult, TError> {
 
   onStateUpdate(
     state: QueryState<TResult, TError>,
+    prevState: QueryState<TResult, TError>,
     action: Action<TResult, TError>
   ): void {
+    // Trigger callbacks on a success event which resulted in a success state
     if (action.type === ActionType.Success && state.isSuccess) {
       this.config.onSuccess?.(state.data!)
       this.config.onSettled?.(state.data!, null)
     }
 
+    // Trigger callbacks on an error event which resulted in an error state
     if (action.type === ActionType.Error && state.isError) {
       this.config.onError?.(state.error!)
       this.config.onSettled?.(undefined, state.error!)
     }
 
-    this.stateUpdateListener?.(state)
+    // Check if we need to notify the subscriber
+    let notify = false
+
+    // Always notify on data and error changes
+    if (state.data !== prevState.data || state.error !== prevState.error) {
+      notify = true
+    }
+
+    // Maybe notify on status changes
+    if (
+      this.config.notifyOnStatusChange &&
+      (state.status !== prevState.status ||
+        state.isFetching !== prevState.isFetching ||
+        state.isFetchingMore !== prevState.isFetchingMore)
+    ) {
+      notify = true
+    }
+
+    // Maybe notify on failureCount changes
+    if (
+      this.config.notifyOnFailureCountChange &&
+      state.failureCount !== prevState.failureCount
+    ) {
+      notify = true
+    }
+
+    // Maybe notify on stale changes
+    if (
+      this.config.notifyOnStaleChange &&
+      state.isStale !== prevState.isStale
+    ) {
+      notify = true
+    }
+
+    if (notify) {
+      this.stateUpdateListener?.(state)
+    }
   }
 }