@tanstack/query-core 4.0.0

package/src/mutation.ts

@@ -0,0 +1,349 @@
+import type { MutationOptions, MutationStatus, MutationMeta } from './types'
+import type { MutationCache } from './mutationCache'
+import type { MutationObserver } from './mutationObserver'
+import { defaultLogger, Logger } from './logger'
+import { notifyManager } from './notifyManager'
+import { Removable } from './removable'
+import { canFetch, Retryer, createRetryer } from './retryer'
+
+// TYPES
+
+interface MutationConfig<TData, TError, TVariables, TContext> {
+  mutationId: number
+  mutationCache: MutationCache
+  options: MutationOptions<TData, TError, TVariables, TContext>
+  logger?: Logger
+  defaultOptions?: MutationOptions<TData, TError, TVariables, TContext>
+  state?: MutationState<TData, TError, TVariables, TContext>
+  meta?: MutationMeta
+}
+
+export interface MutationState<
+  TData = unknown,
+  TError = unknown,
+  TVariables = void,
+  TContext = unknown,
+> {
+  context: TContext | undefined
+  data: TData | undefined
+  error: TError | null
+  failureCount: number
+  isPaused: boolean
+  status: MutationStatus
+  variables: TVariables | undefined
+}
+
+interface FailedAction {
+  type: 'failed'
+}
+
+interface LoadingAction<TVariables, TContext> {
+  type: 'loading'
+  variables?: TVariables
+  context?: TContext
+}
+
+interface SuccessAction<TData> {
+  type: 'success'
+  data: TData
+}
+
+interface ErrorAction<TError> {
+  type: 'error'
+  error: TError
+}
+
+interface PauseAction {
+  type: 'pause'
+}
+
+interface ContinueAction {
+  type: 'continue'
+}
+
+interface SetStateAction<TData, TError, TVariables, TContext> {
+  type: 'setState'
+  state: MutationState<TData, TError, TVariables, TContext>
+}
+
+export type Action<TData, TError, TVariables, TContext> =
+  | ContinueAction
+  | ErrorAction<TError>
+  | FailedAction
+  | LoadingAction<TVariables, TContext>
+  | PauseAction
+  | SetStateAction<TData, TError, TVariables, TContext>
+  | SuccessAction<TData>
+
+// CLASS
+
+export class Mutation<
+  TData = unknown,
+  TError = unknown,
+  TVariables = void,
+  TContext = unknown,
+> extends Removable {
+  state: MutationState<TData, TError, TVariables, TContext>
+  options: MutationOptions<TData, TError, TVariables, TContext>
+  mutationId: number
+  meta: MutationMeta | undefined
+
+  private observers: MutationObserver<TData, TError, TVariables, TContext>[]
+  private mutationCache: MutationCache
+  private logger: Logger
+  private retryer?: Retryer<TData>
+
+  constructor(config: MutationConfig<TData, TError, TVariables, TContext>) {
+    super()
+
+    this.options = {
+      ...config.defaultOptions,
+      ...config.options,
+    }
+    this.mutationId = config.mutationId
+    this.mutationCache = config.mutationCache
+    this.logger = config.logger || defaultLogger
+    this.observers = []
+    this.state = config.state || getDefaultState()
+    this.meta = config.meta
+
+    this.updateCacheTime(this.options.cacheTime)
+    this.scheduleGc()
+  }
+
+  setState(state: MutationState<TData, TError, TVariables, TContext>): void {
+    this.dispatch({ type: 'setState', state })
+  }
+
+  addObserver(observer: MutationObserver<any, any, any, any>): void {
+    if (this.observers.indexOf(observer) === -1) {
+      this.observers.push(observer)
+
+      // Stop the mutation from being garbage collected
+      this.clearGcTimeout()
+
+      this.mutationCache.notify({
+        type: 'observerAdded',
+        mutation: this,
+        observer,
+      })
+    }
+  }
+
+  removeObserver(observer: MutationObserver<any, any, any, any>): void {
+    this.observers = this.observers.filter((x) => x !== observer)
+
+    this.scheduleGc()
+
+    this.mutationCache.notify({
+      type: 'observerRemoved',
+      mutation: this,
+      observer,
+    })
+  }
+
+  protected optionalRemove() {
+    if (!this.observers.length) {
+      if (this.state.status === 'loading') {
+        this.scheduleGc()
+      } else {
+        this.mutationCache.remove(this)
+      }
+    }
+  }
+
+  continue(): Promise<TData> {
+    if (this.retryer) {
+      this.retryer.continue()
+      return this.retryer.promise
+    }
+    return this.execute()
+  }
+
+  async execute(): Promise<TData> {
+    const executeMutation = () => {
+      this.retryer = createRetryer({
+        fn: () => {
+          if (!this.options.mutationFn) {
+            return Promise.reject('No mutationFn found')
+          }
+          return this.options.mutationFn(this.state.variables!)
+        },
+        onFail: () => {
+          this.dispatch({ type: 'failed' })
+        },
+        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
+    }
+
+    const restored = this.state.status === 'loading'
+    try {
+      if (!restored) {
+        this.dispatch({ type: 'loading', variables: this.options.variables! })
+        // Notify cache callback
+        this.mutationCache.config.onMutate?.(
+          this.state.variables,
+          this as Mutation<unknown, unknown, unknown, unknown>,
+        )
+        const context = await this.options.onMutate?.(this.state.variables!)
+        if (context !== this.state.context) {
+          this.dispatch({
+            type: 'loading',
+            context,
+            variables: this.state.variables,
+          })
+        }
+      }
+      const data = await executeMutation()
+
+      // Notify cache callback
+      this.mutationCache.config.onSuccess?.(
+        data,
+        this.state.variables,
+        this.state.context,
+        this as Mutation<unknown, unknown, unknown, unknown>,
+      )
+
+      await this.options.onSuccess?.(
+        data,
+        this.state.variables!,
+        this.state.context!,
+      )
+
+      await this.options.onSettled?.(
+        data,
+        null,
+        this.state.variables!,
+        this.state.context,
+      )
+
+      this.dispatch({ type: 'success', data })
+      return data
+    } catch (error) {
+      try {
+        // Notify cache callback
+        this.mutationCache.config.onError?.(
+          error,
+          this.state.variables,
+          this.state.context,
+          this as Mutation<unknown, unknown, unknown, unknown>,
+        )
+
+        if (process.env.NODE_ENV !== 'production') {
+          this.logger.error(error)
+        }
+
+        await this.options.onError?.(
+          error as TError,
+          this.state.variables!,
+          this.state.context,
+        )
+
+        await this.options.onSettled?.(
+          undefined,
+          error as TError,
+          this.state.variables!,
+          this.state.context,
+        )
+        throw error
+      } finally {
+        this.dispatch({ type: 'error', error: error as TError })
+      }
+    }
+  }
+
+  private dispatch(action: Action<TData, TError, TVariables, TContext>): void {
+    const reducer = (
+      state: MutationState<TData, TError, TVariables, TContext>,
+    ): MutationState<TData, TError, TVariables, TContext> => {
+      switch (action.type) {
+        case 'failed':
+          return {
+            ...state,
+            failureCount: state.failureCount + 1,
+          }
+        case 'pause':
+          return {
+            ...state,
+            isPaused: true,
+          }
+        case 'continue':
+          return {
+            ...state,
+            isPaused: false,
+          }
+        case 'loading':
+          return {
+            ...state,
+            context: action.context,
+            data: undefined,
+            error: null,
+            isPaused: !canFetch(this.options.networkMode),
+            status: 'loading',
+            variables: action.variables,
+          }
+        case 'success':
+          return {
+            ...state,
+            data: action.data,
+            error: null,
+            status: 'success',
+            isPaused: false,
+          }
+        case 'error':
+          return {
+            ...state,
+            data: undefined,
+            error: action.error,
+            failureCount: state.failureCount + 1,
+            isPaused: false,
+            status: 'error',
+          }
+        case 'setState':
+          return {
+            ...state,
+            ...action.state,
+          }
+      }
+    }
+    this.state = reducer(this.state)
+
+    notifyManager.batch(() => {
+      this.observers.forEach((observer) => {
+        observer.onMutationUpdate(action)
+      })
+      this.mutationCache.notify({
+        mutation: this,
+        type: 'updated',
+        action,
+      })
+    })
+  }
+}
+
+export function getDefaultState<
+  TData,
+  TError,
+  TVariables,
+  TContext,
+>(): MutationState<TData, TError, TVariables, TContext> {
+  return {
+    context: undefined,
+    data: undefined,
+    error: null,
+    failureCount: 0,
+    isPaused: false,
+    status: 'idle',
+    variables: undefined,
+  }
+}

package/src/mutationCache.ts

@@ -0,0 +1,157 @@
+import { MutationObserver } from './mutationObserver'
+import type { MutationOptions } from './types'
+import type { QueryClient } from './queryClient'
+import { notifyManager } from './notifyManager'
+import { Action, Mutation, MutationState } from './mutation'
+import { matchMutation, MutationFilters, noop } from './utils'
+import { Subscribable } from './subscribable'
+
+// TYPES
+
+interface MutationCacheConfig {
+  onError?: (
+    error: unknown,
+    variables: unknown,
+    context: unknown,
+    mutation: Mutation<unknown, unknown, unknown>,
+  ) => void
+  onSuccess?: (
+    data: unknown,
+    variables: unknown,
+    context: unknown,
+    mutation: Mutation<unknown, unknown, unknown>,
+  ) => void
+  onMutate?: (
+    variables: unknown,
+    mutation: Mutation<unknown, unknown, unknown, unknown>,
+  ) => void
+}
+
+interface NotifyEventMutationAdded {
+  type: 'added'
+  mutation: Mutation<any, any, any, any>
+}
+interface NotifyEventMutationRemoved {
+  type: 'removed'
+  mutation: Mutation<any, any, any, any>
+}
+
+interface NotifyEventMutationObserverAdded {
+  type: 'observerAdded'
+  mutation: Mutation<any, any, any, any>
+  observer: MutationObserver<any, any, any>
+}
+
+interface NotifyEventMutationObserverRemoved {
+  type: 'observerRemoved'
+  mutation: Mutation<any, any, any, any>
+  observer: MutationObserver<any, any, any>
+}
+
+interface NotifyEventMutationUpdated {
+  type: 'updated'
+  mutation: Mutation<any, any, any, any>
+  action: Action<any, any, any, any>
+}
+
+type MutationCacheNotifyEvent =
+  | NotifyEventMutationAdded
+  | NotifyEventMutationRemoved
+  | NotifyEventMutationObserverAdded
+  | NotifyEventMutationObserverRemoved
+  | NotifyEventMutationUpdated
+
+type MutationCacheListener = (event: MutationCacheNotifyEvent) => void
+
+// CLASS
+
+export class MutationCache extends Subscribable<MutationCacheListener> {
+  config: MutationCacheConfig
+
+  private mutations: Mutation<any, any, any, any>[]
+  private mutationId: number
+
+  constructor(config?: MutationCacheConfig) {
+    super()
+    this.config = config || {}
+    this.mutations = []
+    this.mutationId = 0
+  }
+
+  build<TData, TError, TVariables, TContext>(
+    client: QueryClient,
+    options: MutationOptions<TData, TError, TVariables, TContext>,
+    state?: MutationState<TData, TError, TVariables, TContext>,
+  ): Mutation<TData, TError, TVariables, TContext> {
+    const mutation = new Mutation({
+      mutationCache: this,
+      logger: client.getLogger(),
+      mutationId: ++this.mutationId,
+      options: client.defaultMutationOptions(options),
+      state,
+      defaultOptions: options.mutationKey
+        ? client.getMutationDefaults(options.mutationKey)
+        : undefined,
+      meta: options.meta,
+    })
+
+    this.add(mutation)
+
+    return mutation
+  }
+
+  add(mutation: Mutation<any, any, any, any>): void {
+    this.mutations.push(mutation)
+    this.notify({ type: 'added', mutation })
+  }
+
+  remove(mutation: Mutation<any, any, any, any>): void {
+    this.mutations = this.mutations.filter((x) => x !== mutation)
+    this.notify({ type: 'removed', mutation })
+  }
+
+  clear(): void {
+    notifyManager.batch(() => {
+      this.mutations.forEach((mutation) => {
+        this.remove(mutation)
+      })
+    })
+  }
+
+  getAll(): Mutation[] {
+    return this.mutations
+  }
+
+  find<TData = unknown, TError = unknown, TVariables = any, TContext = unknown>(
+    filters: MutationFilters,
+  ): Mutation<TData, TError, TVariables, TContext> | undefined {
+    if (typeof filters.exact === 'undefined') {
+      filters.exact = true
+    }
+
+    return this.mutations.find((mutation) => matchMutation(filters, mutation))
+  }
+
+  findAll(filters: MutationFilters): Mutation[] {
+    return this.mutations.filter((mutation) => matchMutation(filters, mutation))
+  }
+
+  notify(event: MutationCacheNotifyEvent) {
+    notifyManager.batch(() => {
+      this.listeners.forEach((listener) => {
+        listener(event)
+      })
+    })
+  }
+
+  resumePausedMutations(): Promise<void> {
+    const pausedMutations = this.mutations.filter((x) => x.state.isPaused)
+    return notifyManager.batch(() =>
+      pausedMutations.reduce(
+        (promise, mutation) =>
+          promise.then(() => mutation.continue().catch(noop)),
+        Promise.resolve(),
+      ),
+    )
+  }
+}

package/src/mutationObserver.ts

@@ -0,0 +1,195 @@
+import { Action, getDefaultState, Mutation } from './mutation'
+import { notifyManager } from './notifyManager'
+import type { QueryClient } from './queryClient'
+import { Subscribable } from './subscribable'
+import type {
+  MutateOptions,
+  MutationObserverBaseResult,
+  MutationObserverResult,
+  MutationObserverOptions,
+} from './types'
+
+// TYPES
+
+type MutationObserverListener<TData, TError, TVariables, TContext> = (
+  result: MutationObserverResult<TData, TError, TVariables, TContext>,
+) => void
+
+interface NotifyOptions {
+  listeners?: boolean
+  onError?: boolean
+  onSuccess?: boolean
+}
+
+// CLASS
+
+export class MutationObserver<
+  TData = unknown,
+  TError = unknown,
+  TVariables = void,
+  TContext = unknown,
+> extends Subscribable<
+  MutationObserverListener<TData, TError, TVariables, TContext>
+> {
+  options!: MutationObserverOptions<TData, TError, TVariables, TContext>
+
+  private client: QueryClient
+  private currentResult!: MutationObserverResult<
+    TData,
+    TError,
+    TVariables,
+    TContext
+  >
+  private currentMutation?: Mutation<TData, TError, TVariables, TContext>
+  private mutateOptions?: MutateOptions<TData, TError, TVariables, TContext>
+
+  constructor(
+    client: QueryClient,
+    options: MutationObserverOptions<TData, TError, TVariables, TContext>,
+  ) {
+    super()
+
+    this.client = client
+    this.setOptions(options)
+    this.bindMethods()
+    this.updateResult()
+  }
+
+  protected bindMethods(): void {
+    this.mutate = this.mutate.bind(this)
+    this.reset = this.reset.bind(this)
+  }
+
+  setOptions(
+    options?: MutationObserverOptions<TData, TError, TVariables, TContext>,
+  ) {
+    this.options = this.client.defaultMutationOptions(options)
+  }
+
+  protected onUnsubscribe(): void {
+    if (!this.listeners.length) {
+      this.currentMutation?.removeObserver(this)
+    }
+  }
+
+  onMutationUpdate(action: Action<TData, TError, TVariables, TContext>): void {
+    this.updateResult()
+
+    // Determine which callbacks to trigger
+    const notifyOptions: NotifyOptions = {
+      listeners: true,
+    }
+
+    if (action.type === 'success') {
+      notifyOptions.onSuccess = true
+    } else if (action.type === 'error') {
+      notifyOptions.onError = true
+    }
+
+    this.notify(notifyOptions)
+  }
+
+  getCurrentResult(): MutationObserverResult<
+    TData,
+    TError,
+    TVariables,
+    TContext
+  > {
+    return this.currentResult
+  }
+
+  reset(): void {
+    this.currentMutation = undefined
+    this.updateResult()
+    this.notify({ listeners: true })
+  }
+
+  mutate(
+    variables?: TVariables,
+    options?: MutateOptions<TData, TError, TVariables, TContext>,
+  ): Promise<TData> {
+    this.mutateOptions = options
+
+    if (this.currentMutation) {
+      this.currentMutation.removeObserver(this)
+    }
+
+    this.currentMutation = this.client.getMutationCache().build(this.client, {
+      ...this.options,
+      variables:
+        typeof variables !== 'undefined' ? variables : this.options.variables,
+    })
+
+    this.currentMutation.addObserver(this)
+
+    return this.currentMutation.execute()
+  }
+
+  private updateResult(): void {
+    const state = this.currentMutation
+      ? this.currentMutation.state
+      : getDefaultState<TData, TError, TVariables, TContext>()
+
+    const result: MutationObserverBaseResult<
+      TData,
+      TError,
+      TVariables,
+      TContext
+    > = {
+      ...state,
+      isLoading: state.status === 'loading',
+      isSuccess: state.status === 'success',
+      isError: state.status === 'error',
+      isIdle: state.status === 'idle',
+      mutate: this.mutate,
+      reset: this.reset,
+    }
+
+    this.currentResult = result as MutationObserverResult<
+      TData,
+      TError,
+      TVariables,
+      TContext
+    >
+  }
+
+  private notify(options: NotifyOptions) {
+    notifyManager.batch(() => {
+      // First trigger the mutate callbacks
+      if (this.mutateOptions) {
+        if (options.onSuccess) {
+          this.mutateOptions.onSuccess?.(
+            this.currentResult.data!,
+            this.currentResult.variables!,
+            this.currentResult.context!,
+          )
+          this.mutateOptions.onSettled?.(
+            this.currentResult.data!,
+            null,
+            this.currentResult.variables!,
+            this.currentResult.context,
+          )
+        } else if (options.onError) {
+          this.mutateOptions.onError?.(
+            this.currentResult.error!,
+            this.currentResult.variables!,
+            this.currentResult.context,
+          )
+          this.mutateOptions.onSettled?.(
+            undefined,
+            this.currentResult.error,
+            this.currentResult.variables!,
+            this.currentResult.context,
+          )
+        }
+      }
+
+      // Then trigger the listeners
+      if (options.listeners) {
+        this.listeners.forEach((listener) => {
+          listener(this.currentResult)
+        })
+      }
+    })
+  }
+}