@tanstack/query-core 5.29.0 → 5.32.0

package/src/mutation.ts

@@ -1,6 +1,6 @@
 import { notifyManager } from './notifyManager'
 import { Removable } from './removable'
-import { canFetch, createRetryer } from './retryer'
+import { createRetryer } from './retryer'
 import type {
   DefaultError,
   MutationMeta,
@@ -17,7 +17,6 @@ interface MutationConfig<TData, TError, TVariables, TContext> {
   mutationId: number
   mutationCache: MutationCache
   options: MutationOptions<TData, TError, TVariables, TContext>
-  defaultOptions?: MutationOptions<TData, TError, TVariables, TContext>
   state?: MutationState<TData, TError, TVariables, TContext>
 }
 
@@ -46,6 +45,7 @@ interface FailedAction<TError> {
 
 interface PendingAction<TVariables, TContext> {
   type: 'pending'
+  isPaused: boolean
   variables?: TVariables
   context?: TContext
 }
@@ -89,7 +89,6 @@ export class Mutation<
   readonly mutationId: number
 
   #observers: Array<MutationObserver<TData, TError, TVariables, TContext>>
-  #defaultOptions?: MutationOptions<TData, TError, TVariables, TContext>
   #mutationCache: MutationCache
   #retryer?: Retryer<TData>
 
@@ -97,7 +96,6 @@ export class Mutation<
     super()
 
     this.mutationId = config.mutationId
-    this.#defaultOptions = config.defaultOptions
     this.#mutationCache = config.mutationCache
     this.#observers = []
     this.state = config.state || getDefaultState()
@@ -107,9 +105,9 @@ export class Mutation<
   }
 
   setOptions(
-    options?: MutationOptions<TData, TError, TVariables, TContext>,
+    options: MutationOptions<TData, TError, TVariables, TContext>,
   ): void {
-    this.options = { ...this.#defaultOptions, ...options }
+    this.options = options
 
     this.updateGcTime(this.options.gcTime)
   }
@@ -164,36 +162,34 @@ export class Mutation<
   }
 
   async execute(variables: TVariables): Promise<TData> {
-    const executeMutation = () => {
-      this.#retryer = createRetryer({
-        fn: () => {
-          if (!this.options.mutationFn) {
-            return Promise.reject(new Error('No mutationFn found'))
-          }
-          return this.options.mutationFn(variables)
-        },
-        onFail: (failureCount, error) => {
-          this.#dispatch({ type: 'failed', failureCount, error })
-        },
-        onPause: () => {
-          this.#dispatch({ type: 'pause' })
-        },
-        onContinue: () => {
-          this.#dispatch({ type: 'continue' })
-        },
-        retry: this.options.retry ?? 0,
-        retryDelay: this.options.retryDelay,
-        networkMode: this.options.networkMode,
-      })
-
-      return this.#retryer.promise
-    }
+    this.#retryer = createRetryer({
+      fn: () => {
+        if (!this.options.mutationFn) {
+          return Promise.reject(new Error('No mutationFn found'))
+        }
+        return this.options.mutationFn(variables)
+      },
+      onFail: (failureCount, error) => {
+        this.#dispatch({ type: 'failed', failureCount, error })
+      },
+      onPause: () => {
+        this.#dispatch({ type: 'pause' })
+      },
+      onContinue: () => {
+        this.#dispatch({ type: 'continue' })
+      },
+      retry: this.options.retry ?? 0,
+      retryDelay: this.options.retryDelay,
+      networkMode: this.options.networkMode,
+      canRun: () => this.#mutationCache.canRun(this),
+    })
 
     const restored = this.state.status === 'pending'
+    const isPaused = !this.#retryer.canStart()
 
     try {
       if (!restored) {
-        this.#dispatch({ type: 'pending', variables })
+        this.#dispatch({ type: 'pending', variables, isPaused })
         // Notify cache callback
         await this.#mutationCache.config.onMutate?.(
           variables,
@@ -205,10 +201,11 @@ export class Mutation<
             type: 'pending',
             context,
             variables,
+            isPaused,
           })
         }
       }
-      const data = await executeMutation()
+      const data = await this.#retryer.start()
 
       // Notify cache callback
       await this.#mutationCache.config.onSuccess?.(
@@ -268,6 +265,8 @@ export class Mutation<
       } finally {
         this.#dispatch({ type: 'error', error: error as TError })
       }
+    } finally {
+      this.#mutationCache.runNext(this)
     }
   }
 
@@ -300,7 +299,7 @@ export class Mutation<
             failureCount: 0,
             failureReason: null,
             error: null,
-            isPaused: !canFetch(this.options.networkMode),
+            isPaused: action.isPaused,
             status: 'pending',
             variables: action.variables,
             submittedAt: Date.now(),

package/src/mutationCache.ts

@@ -82,14 +82,13 @@ type MutationCacheListener = (event: MutationCacheNotifyEvent) => void
 // CLASS
 
 export class MutationCache extends Subscribable<MutationCacheListener> {
-  #mutations: Array<Mutation<any, any, any, any>>
+  #mutations: Map<string, Array<Mutation<any, any, any, any>>>
   #mutationId: number
-  #resuming: Promise<unknown> | undefined
 
   constructor(public config: MutationCacheConfig = {}) {
     super()
-    this.#mutations = []
-    this.#mutationId = 0
+    this.#mutations = new Map()
+    this.#mutationId = Date.now()
   }
 
   build<TData, TError, TVariables, TContext>(
@@ -110,25 +109,59 @@ export class MutationCache extends Subscribable<MutationCacheListener> {
   }
 
   add(mutation: Mutation<any, any, any, any>): void {
-    this.#mutations.push(mutation)
+    const scope = scopeFor(mutation)
+    const mutations = this.#mutations.get(scope) ?? []
+    mutations.push(mutation)
+    this.#mutations.set(scope, mutations)
     this.notify({ type: 'added', mutation })
   }
 
   remove(mutation: Mutation<any, any, any, any>): void {
-    this.#mutations = this.#mutations.filter((x) => x !== mutation)
+    const scope = scopeFor(mutation)
+    if (this.#mutations.has(scope)) {
+      const mutations = this.#mutations
+        .get(scope)
+        ?.filter((x) => x !== mutation)
+      if (mutations) {
+        if (mutations.length === 0) {
+          this.#mutations.delete(scope)
+        } else {
+          this.#mutations.set(scope, mutations)
+        }
+      }
+    }
+
     this.notify({ type: 'removed', mutation })
   }
 
+  canRun(mutation: Mutation<any, any, any, any>): boolean {
+    const firstPendingMutation = this.#mutations
+      .get(scopeFor(mutation))
+      ?.find((m) => m.state.status === 'pending')
+
+    // we can run if there is no current pending mutation (start use-case)
+    // or if WE are the first pending mutation (continue use-case)
+    return !firstPendingMutation || firstPendingMutation === mutation
+  }
+
+  runNext(mutation: Mutation<any, any, any, any>): Promise<unknown> {
+    const foundMutation = this.#mutations
+      .get(scopeFor(mutation))
+      ?.find((m) => m !== mutation && m.state.isPaused)
+
+    return foundMutation?.continue() ?? Promise.resolve()
+  }
+
   clear(): void {
     notifyManager.batch(() => {
-      this.#mutations.forEach((mutation) => {
+      this.getAll().forEach((mutation) => {
         this.remove(mutation)
       })
     })
   }
 
   getAll(): Array<Mutation> {
-    return this.#mutations
+    return [...this.#mutations.values()].flat()
   }
 
   find<
@@ -141,15 +174,13 @@ export class MutationCache extends Subscribable<MutationCacheListener> {
   ): Mutation<TData, TError, TVariables, TContext> | undefined {
     const defaultedFilters = { exact: true, ...filters }
 
-    return this.#mutations.find((mutation) =>
+    return this.getAll().find((mutation) =>
       matchMutation(defaultedFilters, mutation),
-    )
+    ) as Mutation<TData, TError, TVariables, TContext> | undefined
   }
 
   findAll(filters: MutationFilters = {}): Array<Mutation> {
-    return this.#mutations.filter((mutation) =>
-      matchMutation(filters, mutation),
-    )
+    return this.getAll().filter((mutation) => matchMutation(filters, mutation))
   }
 
   notify(event: MutationCacheNotifyEvent) {
@@ -161,21 +192,16 @@ export class MutationCache extends Subscribable<MutationCacheListener> {
   }
 
   resumePausedMutations(): Promise<unknown> {
-    this.#resuming = (this.#resuming ?? Promise.resolve())
-      .then(() => {
-        const pausedMutations = this.#mutations.filter((x) => x.state.isPaused)
-        return notifyManager.batch(() =>
-          pausedMutations.reduce(
-            (promise, mutation) =>
-              promise.then(() => mutation.continue().catch(noop)),
-            Promise.resolve() as Promise<unknown>,
-          ),
-        )
-      })
-      .then(() => {
-        this.#resuming = undefined
-      })
+    const pausedMutations = this.getAll().filter((x) => x.state.isPaused)
 
-    return this.#resuming
+    return notifyManager.batch(() =>
+      Promise.all(
+        pausedMutations.map((mutation) => mutation.continue().catch(noop)),
+      ),
+    )
   }
 }
+
+function scopeFor(mutation: Mutation<any, any, any, any>) {
+  return mutation.options.scope?.id ?? String(mutation.mutationId)
+}

package/src/query.ts

@@ -160,7 +160,7 @@ export class Query<
   #revertState?: QueryState<TData, TError>
   #cache: QueryCache
   #retryer?: Retryer<TData>
-  #observers: Array<QueryObserver<any, any, any, any, any>>
+  observers: Array<QueryObserver<any, any, any, any, any>>
   #defaultOptions?: QueryOptions<TQueryFnData, TError, TData, TQueryKey>
   #abortSignalConsumed: boolean
 
@@ -170,7 +170,7 @@ export class Query<
     this.#abortSignalConsumed = false
     this.#defaultOptions = config.defaultOptions
     this.setOptions(config.options)
-    this.#observers = []
+    this.observers = []
     this.#cache = config.cache
     this.queryKey = config.queryKey
     this.queryHash = config.queryHash
@@ -191,7 +191,7 @@ export class Query<
   }
 
   protected optionalRemove() {
-    if (!this.#observers.length && this.state.fetchStatus === 'idle') {
+    if (!this.observers.length && this.state.fetchStatus === 'idle') {
       this.#cache.remove(this)
     }
   }
@@ -238,9 +238,7 @@ export class Query<
   }
 
   isActive(): boolean {
-    return this.#observers.some(
-      (observer) => observer.options.enabled !== false,
-    )
+    return this.observers.some((observer) => observer.options.enabled !== false)
   }
 
   isDisabled(): boolean {
@@ -253,7 +251,7 @@ export class Query<
     }
 
     if (this.getObserversCount() > 0) {
-      return this.#observers.some(
+      return this.observers.some(
         (observer) => observer.getCurrentResult().isStale,
       )
     }
@@ -270,7 +268,7 @@ export class Query<
   }
 
   onFocus(): void {
-    const observer = this.#observers.find((x) => x.shouldFetchOnWindowFocus())
+    const observer = this.observers.find((x) => x.shouldFetchOnWindowFocus())
 
     observer?.refetch({ cancelRefetch: false })
 
@@ -279,7 +277,7 @@ export class Query<
   }
 
   onOnline(): void {
-    const observer = this.#observers.find((x) => x.shouldFetchOnReconnect())
+    const observer = this.observers.find((x) => x.shouldFetchOnReconnect())
 
     observer?.refetch({ cancelRefetch: false })
 
@@ -288,8 +286,8 @@ export class Query<
   }
 
   addObserver(observer: QueryObserver<any, any, any, any, any>): void {
-    if (!this.#observers.includes(observer)) {
-      this.#observers.push(observer)
+    if (!this.observers.includes(observer)) {
+      this.observers.push(observer)
 
       // Stop the query from being garbage collected
       this.clearGcTimeout()
@@ -299,10 +297,10 @@ export class Query<
   }
 
   removeObserver(observer: QueryObserver<any, any, any, any, any>): void {
-    if (this.#observers.includes(observer)) {
-      this.#observers = this.#observers.filter((x) => x !== observer)
+    if (this.observers.includes(observer)) {
+      this.observers = this.observers.filter((x) => x !== observer)
 
-      if (!this.#observers.length) {
+      if (!this.observers.length) {
         // If the transport layer does not support cancellation
         // we'll let the query continue so the result can be cached
         if (this.#retryer) {
@@ -321,7 +319,7 @@ export class Query<
   }
 
   getObserversCount(): number {
-    return this.#observers.length
+    return this.observers.length
   }
 
   invalidate(): void {
@@ -354,7 +352,7 @@ export class Query<
     // Use the options from the first observer with a query function if no function is found.
     // This can happen when the query is hydrated or created with setQueryData.
     if (!this.options.queryFn) {
-      const observer = this.#observers.find((x) => x.options.queryFn)
+      const observer = this.observers.find((x) => x.options.queryFn)
       if (observer) {
         this.setOptions(observer.options)
       }
@@ -527,9 +525,10 @@ export class Query<
       retry: context.options.retry,
       retryDelay: context.options.retryDelay,
       networkMode: context.options.networkMode,
+      canRun: () => true,
     })
 
-    return this.#retryer.promise
+    return this.#retryer.start()
   }
 
   #dispatch(action: Action<TData, TError>): void {
@@ -607,7 +606,7 @@ export class Query<
     this.state = reducer(this.state)
 
     notifyManager.batch(() => {
-      this.#observers.forEach((observer) => {
+      this.observers.forEach((observer) => {
         observer.onQueryUpdate()
       })
 

package/src/retryer.ts

@@ -16,6 +16,7 @@ interface RetryerConfig<TData = unknown, TError = DefaultError> {
   retry?: RetryValue<TError>
   retryDelay?: RetryDelayValue<TError>
   networkMode: NetworkMode | undefined
+  canRun: () => boolean
 }
 
 export interface Retryer<TData = unknown> {
@@ -24,6 +25,8 @@ export interface Retryer<TData = unknown> {
   continue: () => Promise<unknown>
   cancelRetry: () => void
   continueRetry: () => void
+  canStart: () => boolean
+  start: () => Promise<TData>
 }
 
 export type RetryValue<TError> = boolean | number | ShouldRetryFunction<TError>
@@ -69,7 +72,7 @@ export function createRetryer<TData = unknown, TError = DefaultError>(
   let isRetryCancelled = false
   let failureCount = 0
   let isResolved = false
-  let continueFn: ((value?: unknown) => boolean) | undefined
+  let continueFn: ((value?: unknown) => void) | undefined
   let promiseResolve: (data: TData) => void
   let promiseReject: (error: TError) => void
 
@@ -93,9 +96,12 @@ export function createRetryer<TData = unknown, TError = DefaultError>(
     isRetryCancelled = false
   }
 
-  const shouldPause = () =>
-    !focusManager.isFocused() ||
-    (config.networkMode !== 'always' && !onlineManager.isOnline())
+  const canContinue = () =>
+    focusManager.isFocused() &&
+    (config.networkMode === 'always' || onlineManager.isOnline()) &&
+    config.canRun()
+
+  const canStart = () => canFetch(config.networkMode) && config.canRun()
 
   const resolve = (value: any) => {
     if (!isResolved) {
@@ -118,11 +124,9 @@ export function createRetryer<TData = unknown, TError = DefaultError>(
   const pause = () => {
     return new Promise((continueResolve) => {
       continueFn = (value) => {
-        const canContinue = isResolved || !shouldPause()
-        if (canContinue) {
+        if (isResolved || canContinue()) {
           continueResolve(value)
         }
-        return canContinue
       }
       config.onPause?.()
     }).then(() => {
@@ -184,10 +188,7 @@ export function createRetryer<TData = unknown, TError = DefaultError>(
         sleep(delay)
           // Pause if the document is not visible or when the device is offline
           .then(() => {
-            if (shouldPause()) {
-              return pause()
-            }
-            return
+            return canContinue() ? undefined : pause()
           })
           .then(() => {
             if (isRetryCancelled) {
@@ -199,21 +200,24 @@ export function createRetryer<TData = unknown, TError = DefaultError>(
       })
   }
 
-  // Start loop
-  if (canFetch(config.networkMode)) {
-    run()
-  } else {
-    pause().then(run)
-  }
-
   return {
     promise,
     cancel,
     continue: () => {
-      const didContinue = continueFn?.()
-      return didContinue ? promise : Promise.resolve()
+      continueFn?.()
+      return promise
     },
     cancelRetry,
     continueRetry,
+    canStart,
+    start: () => {
+      // Start loop
+      if (canStart()) {
+        run()
+      } else {
+        pause().then(run)
+      }
+      return promise
+    },
   }
 }

package/src/types.ts

@@ -717,6 +717,10 @@ export type MutationKey = ReadonlyArray<unknown>
 
 export type MutationStatus = 'idle' | 'pending' | 'success' | 'error'
 
+export type MutationScope = {
+  id: string
+}
+
 export type MutationMeta = Register extends {
   mutationMeta: infer TMutationMeta
 }
@@ -762,6 +766,7 @@ export interface MutationOptions<
   gcTime?: number
   _defaulted?: boolean
   meta?: MutationMeta
+  scope?: MutationScope
 }
 
 export interface MutationObserverOptions<