Incorporate review suggestions

Author: Georg Wicke-Arndt

packages/toolkit/src/query/apiTypes.ts

@@ -45,7 +45,7 @@ export type Module<Name extends ModuleName> = {
       | 'refetchOnMountOrArgChange'
       | 'refetchOnFocus'
       | 'refetchOnReconnect'
-      | 'invalidateImmediately'
+      | 'invalidationBehavior'
       | 'tagTypes'
     >,
     context: ApiContext<Definitions>

packages/toolkit/src/query/core/apiState.ts

@@ -7,7 +7,6 @@ import type {
   BaseEndpointDefinition,
   ResultTypeFrom,
   QueryArgFrom,
-  FullTagDescription,
 } from '../endpointDefinitions'
 import type { Id, WithRequiredProp } from '../tsHelpers'
 
@@ -255,7 +254,7 @@ export type ConfigState<ReducerPath> = RefetchConfigOptions & {
 
 export type ModifiableConfigState = {
   keepUnusedDataFor: number
-  invalidateImmediately: boolean
+  invalidationBehavior: 'delayed' | 'immediately'
 } & RefetchConfigOptions
 
 export type MutationState<D extends EndpointDefinitions> = {

packages/toolkit/src/query/core/buildMiddleware/invalidationByTags.ts

@@ -84,11 +84,11 @@ export const buildInvalidationByTagsHandler: InternalHandlerBuilder = ({
 
     pendingTagInvalidations.push(...newTags)
 
-    if (!state.config.invalidateImmediately) {
-      const hasPendingRequests = Object.values({
-        ...state.queries,
-        ...state.mutations,
-      }).some((x) => x?.status === QueryStatus.pending)
+    if (state.config.invalidationBehavior === 'delayed') {
+      const hasPendingRequests = [
+        ...Object.values(state.queries),
+        ...Object.values(state.mutations),
+      ].some((x) => x?.status === QueryStatus.pending)
 
       if (hasPendingRequests) return
     }

packages/toolkit/src/query/core/buildSlice.ts

@@ -28,7 +28,6 @@ import { calculateProvidedByThunk } from './buildThunks'
 import type {
   AssertTagTypes,
   EndpointDefinitions,
-  FullTagDescription,
   QueryDefinition,
 } from '../endpointDefinitions'
 import type { Patch } from 'immer'

packages/toolkit/src/query/core/module.ts

@@ -452,7 +452,7 @@ export const coreModule = (): Module<CoreModule> => ({
       refetchOnMountOrArgChange,
       refetchOnFocus,
       refetchOnReconnect,
-      invalidateImmediately,
+      invalidationBehavior,
     },
     context
   ) {
@@ -515,7 +515,7 @@ export const coreModule = (): Module<CoreModule> => ({
         refetchOnMountOrArgChange,
         keepUnusedDataFor,
         reducerPath,
-        invalidateImmediately,
+        invalidationBehavior,
       },
     })
 

packages/toolkit/src/query/createApi.ts

@@ -152,14 +152,15 @@ export interface CreateApiOptions<
    */
   refetchOnReconnect?: boolean
   /**
-   * Defaults to `false`. This setting allows you to disable a consistency measure that delay tag invalidations until all pending queries and mutations are settled.
+   * Defaults to `'immediately'`. This setting allows you to control when tags are invalidated after a mutation.
    *
-   * Context: If a mutation finishes while a query is pending, then RTK-query has to wait until the query is finished until it can invalidate any tags, since the query itself could provide a tag that the mutation will invalidate.
-   * RTK-query also waits with the tag invalidations if another mutation is pending, to "batch" the tag invalidations if two mutations invalidate the same tag, avoiding unnecessary re-fetching.
-   *
-   * If you constantly have some queries running, this can delay the tag invalidations. In this case, you can enable this setting to opt-out of the "correct" behavior and refetch immediately when a mutation finishes instead.
+   * - `'immediately'`: Queries are invalidated instantly after the mutation finished, even if they are running.
+   *   If the query provides tags that were invalidated while it ran, it won't be re-fetched.
+   * - `'delayed'`: Invalidation only happens after all queries and mutations are settled.
+   *   This ensures that queries are always invalidated correctly and automatically "batches" invalidations of concurrent mutations.
+   *   Note that if you constantly have some queries (or mutations) running, this can delay tag invalidations indefinitely.
    */
-  invalidateImmediately?: boolean
+  invalidationBehavior?: 'delayed' | 'immediately'
   /**
    * A function that is passed every dispatched action. If this returns something other than `undefined`,
    * that return value will be used to rehydrate fulfilled & errored queries.
@@ -264,7 +265,7 @@ export function buildCreateApi<Modules extends [Module<any>, ...Module<any>[]]>(
       refetchOnMountOrArgChange: false,
       refetchOnFocus: false,
       refetchOnReconnect: false,
-      invalidateImmediately: false,
+      invalidationBehavior: 'delayed',
       ...options,
       extractRehydrationInfo,
       serializeQueryArgs(queryArgsApi) {

packages/toolkit/src/query/tests/buildSlice.test.ts

@@ -51,7 +51,7 @@ describe('buildSlice', () => {
       api: {
         config: {
           focused: true,
-          invalidateImmediately: false,
+          invalidationBehavior: "delayed",
           keepUnusedDataFor: 60,
           middlewareRegistered: true,
           online: true,