replace getRunningOperationPromise(s) with getRunning(Query|Queries|Mutation|Mutations)Thunk

Author: phryneas

docs/rtk-query/api/created-api/api-slice-utils.mdx

@@ -249,53 +249,59 @@ Note that [hooks](./hooks.mdx) also track state in local component state and mig
 dispatch(api.util.resetApiState())
 ```
 
-## `getRunningOperationPromises`
+## `getRunningQueriesThunk` and `getRunningMutationsThunk`
 
 #### Signature
 
 ```ts no-transpile
-getRunningOperationPromises: () => Array<Promise<unknown>>
+getRunningQueriesThunk(): ThunkWithReturnValue<Array<QueryActionCreatorResult<any>>>
+getRunningMutationsThunk(): ThunkWithReturnValue<Array<MutationActionCreatorResult<any>>>
 ```
 
 #### Description
 
-A function that returns all promises for running queries and mutations.
+Thunks that (if dispatched) return either all running queries or mutations.
+These returned values can be awaited like promises.
 
-This is useful for SSR scenarios to await everything triggered in any way, including via hook calls,
+This is useful for SSR scenarios to await all queries (or mutations) triggered in any way, including via hook calls
 or manually dispatching `initiate` actions.
 
-```ts no-transpile title="Awaiting all currently running queries & mutations example"
-await Promise.all(api.util.getRunningOperationPromises())
+```ts no-transpile title="Awaiting all currently running queries example"
+await Promise.all(dispatch(api.util.getRunningQueriesThunk()))
 ```
 
-## `getRunningOperationPromise`
+## `getRunningQueryThunk` and `getRunningMutationThunk`
 
 #### Signature
 
 ```ts no-transpile
-getRunningOperationPromise: <EndpointName extends QueryKeys<Definitions>>(
+getRunningQueryThunk<EndpointName extends QueryKeys<Definitions>>(
   endpointName: EndpointName,
   args: QueryArgFrom<Definitions[EndpointName]>
-) =>
-  | QueryActionCreatorResult<Definitions[EndpointName]>
+): ThunkWithReturnValue<
+  | QueryActionCreatorResult<
+      Definitions[EndpointName] & { type: 'query' }
+    >
   | undefined
+>
 
-getRunningOperationPromise: <EndpointName extends MutationKeys<Definitions>>(
+getRunningMutationThunk<EndpointName extends MutationKeys<Definitions>>(
   endpointName: EndpointName,
   fixedCacheKeyOrRequestId: string
-) =>
-  | MutationActionCreatorResult<Definitions[EndpointName]>
+): ThunkWithReturnValue<
+  | MutationActionCreatorResult<
+      Definitions[EndpointName] & { type: 'mutation' }
+    >
   | undefined
+>
 ```
 
 #### Description
 
-A function that returns a single promise for a given endpoint name + argument combination,
-if it is currently running. If it is not currently running, the function returns `undefined`.
+Thunks that (if dispatched) return a single running query (or mutation) for a given
+endpoint name + argument (or requestId/fixedCacheKey) combination, if it is currently running.
+If it is not currently running, the function returns `undefined`.
 
-When used with mutation endpoints, it accepts a [fixed cache key](./hooks.mdx#signature-1)
-or request ID rather than the argument.
-
-This is primarily added to add experimental support for suspense in the future.
-It enables writing custom hooks that look up if RTK Query has already got a running promise
-for a certain endpoint/argument combination, and retrieving that promise to `throw` it.
+These thunks are primarily added to add experimental support for suspense in the future.
+They enable writing custom hooks that look up if RTK Query has already got a running query/mutation
+for a certain endpoint/argument combination, and retrieving that to `throw` it as a promise.

docs/rtk-query/api/created-api/overview.mdx

@@ -53,20 +53,29 @@ type Api = {
       Array<TagTypes | FullTagDescription<TagTypes>>,
       string
     >
-    resetApiState: SliceActions['resetApiState']
-    getRunningOperationPromises: () => Array<Promise<unknown>>
-    getRunningOperationPromise: <EndpointName extends QueryKeys<Definitions>>(
+    selectInvalidatedBy: (
+      state: FullState,
+      tags: Array<TagTypes | FullTagDescription<TagTypes>>
+    ) => Array<{
+      endpointName: string
+      originalArgs: any
+      queryCacheKey: string
+    }>
+    resetApiState: ActionCreator<ResetAction>
+    getRunningQueryThunk(
       endpointName: EndpointName,
-      args: QueryArgFrom<Definitions[EndpointName]>
-    ) =>
-      | QueryActionCreatorResult<Definitions[EndpointName]>
-      | undefined
-    getRunningOperationPromise: <EndpointName extends MutationKeys<Definitions>>(
+      args: QueryArg
+    ): ThunkWithReturnValue<QueryActionCreatorResult | undefined>
+    getRunningMutationThunk(
       endpointName: EndpointName,
       fixedCacheKeyOrRequestId: string
-    ) =>
-      | MutationActionCreatorResult<Definitions[EndpointName]>
-      | undefined
+    ): ThunkWithReturnValue<MutationActionCreatorResult | undefined>
+    getRunningQueriesThunk(): ThunkWithReturnValue<
+      Array<QueryActionCreatorResult<any>>
+    >
+    getRunningMutationsThunk(): ThunkWithReturnValue<
+      Array<MutationActionCreatorResult<any>>
+    >
   }
 
   // Internal actions

docs/rtk-query/usage/server-side-rendering.mdx

@@ -21,7 +21,7 @@ The workflow is as follows:
 - Set up `next-redux-wrapper`
 - In `getStaticProps` or `getServerSideProps`:
   - Pre-fetch all queries via the `initiate` actions, e.g. `store.dispatch(api.endpoints.getPokemonByName.initiate(name))`
-  - Wait for each query to finish using `await Promise.all(api.util.getRunningOperationPromises())`
+  - Wait for each query to finish using `await Promise.all(dispatch(api.util.getRunningQueriesThunk()))`
 - In your `createApi` call, configure rehydration using the `extractRehydrationInfo` option:
 
   [examples](docblock://query/createApi.ts?token=CreateApiOptions.extractRehydrationInfo)
@@ -56,4 +56,4 @@ The workflow is as follows:
   [examples](docblock://query/react/module.ts?token=ReactHooksModuleOptions.unstable__sideEffectsInRender)
 
 - Use your custom `createApi` when calling `const api = createApi({...})`
-- Wait for all queries to finish using `await Promise.all(api.util.getRunningOperationPromises())` before performing the next render cycle
+- Wait for all queries to finish using `await Promise.all(dispatch(api.util.getRunningQueriesThunk()))` before performing the next render cycle

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

@@ -14,7 +14,7 @@ import type { Api, ApiContext } from '../apiTypes'
 import type { ApiEndpointQuery } from './module'
 import type { BaseQueryError, QueryReturnValue } from '../baseQueryTypes'
 import type { QueryResultSelectorResult } from './buildSelectors'
-import { Dispatch } from 'redux'
+import type { Dispatch } from 'redux'
 
 declare module './module' {
   export interface ApiEndpointQuery<
@@ -214,40 +214,53 @@ export function buildInitiate({
   return {
     buildInitiateQuery,
     buildInitiateMutation,
-    getRunningOperationPromises,
-    getRunningOperationPromise,
+    getRunningQueryThunk,
+    getRunningMutationThunk,
+    getRunningQueriesThunk,
+    getRunningMutationsThunk,
   }
 
-  function getRunningOperationPromise(
-    endpointName: string,
-    argOrRequestId: any
-  ): ThunkAction<any, any, any, AnyAction> {
+  function getRunningQueryThunk(endpointName: string, queryArgs: any) {
     return (dispatch: Dispatch) => {
       const endpointDefinition = context.endpointDefinitions[endpointName]
-      if (endpointDefinition.type === DefinitionType.query) {
-        const queryCacheKey = serializeQueryArgs({
-          queryArgs: argOrRequestId,
-          endpointDefinition,
-          endpointName,
-        })
-        return runningQueries.get(dispatch)?.[queryCacheKey]
-      } else {
-        return runningMutations.get(dispatch)?.[argOrRequestId]
-      }
+      const queryCacheKey = serializeQueryArgs({
+        queryArgs,
+        endpointDefinition,
+        endpointName,
+      })
+      return runningQueries.get(dispatch)?.[queryCacheKey] as
+        | QueryActionCreatorResult<never>
+        | undefined
     }
   }
 
-  function getRunningOperationPromises(): ThunkAction<
-    Promise<unknown>[],
-    any,
-    any,
-    AnyAction
-  > {
+  function getRunningMutationThunk(
+    /**
+     * this is only here to allow TS to infer the result type by input value
+     * we could use it to validate the result, but it's probably not necessary
+     */
+    _endpointName: string,
+    fixedCacheKeyOrRequestId: string
+  ) {
+    return (dispatch: Dispatch) => {
+      return runningMutations.get(dispatch)?.[fixedCacheKeyOrRequestId] as
+        | MutationActionCreatorResult<never>
+        | undefined
+    }
+  }
+
+  function getRunningQueriesThunk() {
+    return (dispatch: Dispatch) =>
+      Object.values(runningQueries.get(dispatch) || {}).filter(
+        <T>(t: T | undefined): t is T => !!t
+      )
+  }
+
+  function getRunningMutationsThunk() {
     return (dispatch: Dispatch) =>
-      [
-        ...Object.values(runningQueries.get(dispatch) || {}),
-        ...Object.values(runningMutations.get(dispatch) || {}),
-      ].filter(<T>(t: T | undefined): t is T => !!t)
+      Object.values(runningMutations.get(dispatch) || {}).filter(
+        <T>(t: T | undefined): t is T => !!t
+      )
   }
 
   function middlewareWarning(getState: () => RootState<{}, string, string>) {

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

@@ -71,6 +71,9 @@ export type CoreModule =
   | ReferenceQueryLifecycle
   | ReferenceCacheCollection
 
+interface ThunkWithReturnValue<T>
+  extends ThunkAction<T | undefined, any, any, AnyAction> {}
+
 declare module '../apiTypes' {
   export interface ApiModules<
     // eslint-disable-next-line @typescript-eslint/no-unused-vars
@@ -138,47 +141,81 @@ declare module '../apiTypes' {
        */
       util: {
         /**
-         * Returns all promises for running queries and mutations.
-         * Useful for SSR scenarios to await everything triggered in any way,
-         * including via hook calls, or manually dispatching `initiate` actions.
+         * This method had to be removed due to a conceptual bug in RTK.
+         * Please see https://redux-toolkit.js.org/rtk-query/usage/server-side-rendering for details.
+         * @deprecated
          */
-        getRunningOperationPromises: () => ThunkAction<
-          Array<Promise<unknown>>,
-          any,
-          any,
-          AnyAction
-        >
+        getRunningOperationPromises: never // this is now types as `never` to immediately throw TS errors on use, but still allow for a comment
+
         /**
-         * If a promise is running for a given endpoint name + argument combination,
-         * returns that promise. Otherwise, returns `undefined`.
-         * Can be used to await a specific query/mutation triggered in any way,
-         * including via hook calls, or manually dispatching `initiate` actions.
+         * This method had to be removed due to a conceptual bug in RTK.
+         * Please see https://redux-toolkit.js.org/rtk-query/usage/server-side-rendering for details.
+         * @deprecated
+         */
+        getRunningOperationPromise: never // this is now types as `never` to immediately throw TS errors on use, but still allow for a comment
+
+        /**
+         * A thunk that (if dispatched) will return a specific running query, identified
+         * by `endpointName` and `args`.
+         * If that query is not running, dispatching the thunk will result in `undefined`.
+         *
+         * Can be used to await a specific query triggered in any way,
+         * including via hook calls or manually dispatching `initiate` actions.
+         *
+         * See https://redux-toolkit.js.org/rtk-query/usage/server-side-rendering for details.
          */
-        getRunningOperationPromise<EndpointName extends QueryKeys<Definitions>>(
+        getRunningQueryThunk<EndpointName extends QueryKeys<Definitions>>(
           endpointName: EndpointName,
           args: QueryArgFrom<Definitions[EndpointName]>
-        ): ThunkAction<
+        ): ThunkWithReturnValue<
           | QueryActionCreatorResult<
               Definitions[EndpointName] & { type: 'query' }
             >
-          | undefined,
-          any,
-          any,
-          AnyAction
+          | undefined
         >
-        getRunningOperationPromise<
-          EndpointName extends MutationKeys<Definitions>
-        >(
+
+        /**
+         * A thunk that (if dispatched) will return a specific running mutation, identified
+         * by `endpointName` and `fixedCacheKey` or `requestId`.
+         * If that mutation is not running, dispatching the thunk will result in `undefined`.
+         *
+         * Can be used to await a specific mutation triggered in any way,
+         * including via hook trigger functions or manually dispatching `initiate` actions.
+         *
+         * See https://redux-toolkit.js.org/rtk-query/usage/server-side-rendering for details.
+         */
+        getRunningMutationThunk<EndpointName extends MutationKeys<Definitions>>(
           endpointName: EndpointName,
           fixedCacheKeyOrRequestId: string
-        ): ThunkAction<
+        ): ThunkWithReturnValue<
           | MutationActionCreatorResult<
               Definitions[EndpointName] & { type: 'mutation' }
             >
-          | undefined,
-          any,
-          any,
-          AnyAction
+          | undefined
+        >
+
+        /**
+         * A thunk that (if dispatched) will return all running queries.
+         *
+         * Useful for SSR scenarios to await all running queries triggered in any way,
+         * including via hook calls or manually dispatching `initiate` actions.
+         *
+         * See https://redux-toolkit.js.org/rtk-query/usage/server-side-rendering for details.
+         */
+        getRunningQueriesThunk(): ThunkWithReturnValue<
+          Array<QueryActionCreatorResult<any>>
+        >
+
+        /**
+         * A thunk that (if dispatched) will return all running mutations.
+         *
+         * Useful for SSR scenarios to await all running mutations triggered in any way,
+         * including via hook calls or manually dispatching `initiate` actions.
+         *
+         * See https://redux-toolkit.js.org/rtk-query/usage/server-side-rendering for details.
+         */
+        getRunningMutationsThunk(): ThunkWithReturnValue<
+          Array<MutationActionCreatorResult<any>>
         >
 
         /**
@@ -307,6 +344,11 @@ declare module '../apiTypes' {
           string
         >
 
+        /**
+         * A function to select all `{ endpointName, originalArgs, queryCacheKey }` combinations that would be invalidated by a specific set of tags.
+         *
+         * Can be used for mutations that want to do optimistic updates instead of invalidating a set of tags, but don't know exactly what they need to update.
+         */
         selectInvalidatedBy: (
           state: RootState<Definitions, string, ReducerPath>,
           tags: ReadonlyArray<TagDescription<TagTypes>>
@@ -495,8 +537,10 @@ export const coreModule = (): Module<CoreModule> => ({
     const {
       buildInitiateQuery,
       buildInitiateMutation,
-      getRunningOperationPromises,
-      getRunningOperationPromise,
+      getRunningMutationThunk,
+      getRunningMutationsThunk,
+      getRunningQueriesThunk,
+      getRunningQueryThunk,
     } = buildInitiate({
       queryThunk,
       mutationThunk,
@@ -505,9 +549,20 @@ export const coreModule = (): Module<CoreModule> => ({
       context,
     })
 
+    function removedSSRHelper(): never {
+      throw new Error(
+        `This method had to be removed due to a conceptual bug in RTK.
+         Please see https://redux-toolkit.js.org/rtk-query/usage/server-side-rendering for details.`
+      )
+    }
+
     safeAssign(api.util, {
-      getRunningOperationPromises,
-      getRunningOperationPromise,
+      getRunningOperationPromises: removedSSRHelper as any,
+      getRunningOperationPromise: removedSSRHelper as any,
+      getRunningMutationThunk,
+      getRunningMutationsThunk,
+      getRunningQueryThunk,
+      getRunningQueriesThunk,
     })
 
     return {