fix(ui): database errors when running autosave and ensure autosave doesn't run unnecessarily (#11270)

## Change 1 - database errors when running autosave

The previous autosave implementation allowed multiple autosave fetch
calls (=> save document draft) to run in parallel. While the
AbortController aborted previous autosave calls if a new one comes in in
order to only process the latest one, this had one flaw:

Using the AbortController to abort the autosave call only aborted the
`fetch` call - it did not however abort the database operation that may
have started as part of this fetch call. If you then started a new
autosave call, this will start yet another database operation on the
backend, resulting in two database operations that would be running at
the same time.

This has caused a lot of transaction errors that were only noticeable
when connected to a slower, remote database. This PR removes the
AbortController and ensures that the previous autosave operation is
properly awaited before starting a new one, while still discarding
outdated autosave requests from the queue **that have not started yet**.

Additionally, it cleans up the AutoSave component to make it more
readable.

## Change 2 - ensure autosave doesn't run unnecessarily

If connected to a slower backend or database, one change in a document
may trigger two autosave operations instead of just one. This is how it
could happen:

1. Type something => formstate changes => autosave is triggered
2. 200ms later: form state request is triggered. Autosave is still
processing
3. 100ms later: form state comes back from server => local form state is
updated => another autosave is triggered
4. First autosave is aborted - this lead to a browser error. This PR
ensures that that error is no longer surfaced to the user
5. Another autosave is started

This PR adds additional checks to ONLY trigger an autosave if the form
DATA (not the entire form state itself) changes. Previously, it ran
every time the object reference of the form state changes. This includes
changes that do not affect the form data, like `field.valid`. =>
Basically every time form state comes back from the server, we were
triggering another, unnecessary autosave

Author: AlessioGr

packages/ui/src/elements/Autosave/index.tsx

@@ -2,8 +2,9 @@
 // TODO: abstract the `next/navigation` dependency out from this component
 import type { ClientCollectionConfig, ClientGlobalConfig } from 'payload'
 
-import { versionDefaults } from 'payload/shared'
-import React, { useEffect, useRef, useState } from 'react'
+import { dequal } from 'dequal/lite'
+import { reduceFieldsToValues, versionDefaults } from 'payload/shared'
+import React, { useDeferredValue, useEffect, useRef, useState } from 'react'
 import { toast } from 'sonner'
 
 import {
@@ -18,8 +19,8 @@ import { useConfig } from '../../providers/Config/index.js'
 import { useDocumentEvents } from '../../providers/DocumentEvents/index.js'
 import { useDocumentInfo } from '../../providers/DocumentInfo/index.js'
 import { useLocale } from '../../providers/Locale/index.js'
-import { useTranslation } from '../../providers/Translation/index.js'
 import './index.scss'
+import { useTranslation } from '../../providers/Translation/index.js'
 import { formatTimeToNow } from '../../utilities/formatDate.js'
 import { reduceFieldsToValuesWithValidation } from '../../utilities/reduceFieldsToValuesWithValidation.js'
 import { LeaveWithoutSaving } from '../LeaveWithoutSaving/index.js'
@@ -76,7 +77,8 @@ export const Autosave: React.FC<Props> = ({ id, collection, global: globalDoc })
     docConfig?.versions?.drafts && docConfig?.versions?.drafts.validate,
   )
 
-  const [saving, setSaving] = useState(false)
+  const [_saving, setSaving] = useState(false)
+  const saving = useDeferredValue(_saving)
   const debouncedFields = useDebounce(fields, interval)
   const fieldRef = useRef(fields)
   const modifiedRef = useRef(modified)
@@ -86,9 +88,6 @@ export const Autosave: React.FC<Props> = ({ id, collection, global: globalDoc })
    * Helps us prevent infinite loops when the queue is processing and the form is invalid
    */
   const isValidRef = useRef(isValid)
-  const debouncedRef = useRef(debouncedFields)
-
-  debouncedRef.current = debouncedFields
 
   // Store fields in ref so the autosave func
   // can always retrieve the most to date copies
@@ -116,8 +115,8 @@ export const Autosave: React.FC<Props> = ({ id, collection, global: globalDoc })
       isValidRef.current = true
       return
     }
-
     isProcessingRef.current = true
+
     const latestAction = queueRef.current[queueRef.current.length - 1]
     queueRef.current = []
 
@@ -131,13 +130,28 @@ export const Autosave: React.FC<Props> = ({ id, collection, global: globalDoc })
     }
   }, [])
 
+  const autosaveTimeoutRef = useRef<NodeJS.Timeout | null>(null)
+
   const handleAutosave = useEffectEvent(() => {
-    const abortController = new AbortController()
-    let autosaveTimeout = undefined
+    autosaveTimeoutRef.current = undefined
     // We need to log the time in order to figure out if we need to trigger the state off later
     let startTimestamp = undefined
     let endTimestamp = undefined
 
+    const hideIndicator = () => {
+      // If request was faster than minimum animation time, animate the difference
+      if (endTimestamp - startTimestamp < minimumAnimationTime) {
+        autosaveTimeoutRef.current = setTimeout(
+          () => {
+            setSaving(false)
+          },
+          minimumAnimationTime - (endTimestamp - startTimestamp),
+        )
+      } else {
+        stopAutoSaveIndicator()
+      }
+    }
+
     const autosave = async () => {
       if (modified) {
         startTimestamp = new Date().getTime()
@@ -162,120 +176,110 @@ export const Autosave: React.FC<Props> = ({ id, collection, global: globalDoc })
 
         if (url) {
           if (modifiedRef.current) {
-            const { data, valid } = {
-              ...reduceFieldsToValuesWithValidation(fieldRef.current, true),
-            }
+            const { data, valid } = reduceFieldsToValuesWithValidation(fieldRef.current, true)
+
             data._status = 'draft'
+
             const skipSubmission =
               submitted && !valid && versionsConfig?.drafts && versionsConfig?.drafts?.validate
 
             if (!skipSubmission && isValidRef.current) {
-              await fetch(url, {
-                body: JSON.stringify(data),
-                credentials: 'include',
-                headers: {
-                  'Accept-Language': i18n.language,
-                  'Content-Type': 'application/json',
-                },
-                method,
-                signal: abortController.signal,
-              })
-                .then((res) => {
-                  const newDate = new Date()
-                  // We need to log the time in order to figure out if we need to trigger the state off later
-                  endTimestamp = newDate.getTime()
-
-                  if (res.status === 200) {
-                    setLastUpdateTime(newDate.getTime())
-
-                    reportUpdate({
-                      id,
-                      entitySlug,
-                      updatedAt: newDate.toISOString(),
-                    })
-
-                    if (!mostRecentVersionIsAutosaved) {
-                      incrementVersionCount()
-                      setMostRecentVersionIsAutosaved(true)
-                      setUnpublishedVersionCount((prev) => prev + 1)
-                    }
-                  }
-
-                  return res.json()
+              let res
+              try {
+                res = await fetch(url, {
+                  body: JSON.stringify(data),
+                  credentials: 'include',
+                  headers: {
+                    'Accept-Language': i18n.language,
+                    'Content-Type': 'application/json',
+                  },
+                  method,
                 })
-                .then((json) => {
-                  if (versionsConfig?.drafts && versionsConfig?.drafts?.validate && json?.errors) {
-                    if (Array.isArray(json.errors)) {
-                      const [fieldErrors, nonFieldErrors] = json.errors.reduce(
-                        ([fieldErrs, nonFieldErrs], err) => {
-                          const newFieldErrs = []
-                          const newNonFieldErrs = []
-
-                          if (err?.message) {
-                            newNonFieldErrs.push(err)
-                          }
+              } catch (error) {
+                // Swallow Error
+              }
 
-                          if (Array.isArray(err?.data)) {
-                            err.data.forEach((dataError) => {
-                              if (dataError?.field) {
-                                newFieldErrs.push(dataError)
-                              } else {
-                                newNonFieldErrs.push(dataError)
-                              }
-                            })
-                          }
+              const newDate = new Date()
+              // We need to log the time in order to figure out if we need to trigger the state off later
+              endTimestamp = newDate.getTime()
 
-                          return [
-                            [...fieldErrs, ...newFieldErrs],
-                            [...nonFieldErrs, ...newNonFieldErrs],
-                          ]
-                        },
-                        [[], []],
-                      )
-
-                      dispatchFields({
-                        type: 'ADD_SERVER_ERRORS',
-                        errors: fieldErrors,
-                      })
-
-                      nonFieldErrors.forEach((err) => {
-                        toast.error(err.message || i18n.t('error:unknown'))
-                      })
-
-                      // Set valid to false internally so the queue doesn't process
-                      isValidRef.current = false
-                      setIsValid(false)
-                      setSubmitted(true)
-
-                      return
-                    }
-                  } else {
-                    // If it's not an error then we can update the document data inside the context
-                    const document = json?.doc || json?.result
-
-                    // Manually update the data since this function doesn't fire the `submit` function from useForm
-                    if (document) {
-                      setIsValid(true)
-
-                      // Reset internal state allowing the queue to process
-                      isValidRef.current = true
-                      updateSavedDocumentData(document)
-                    }
-                  }
-                })
-                .finally(() => {
-                  // If request was faster than minimum animation time, animate the difference
-                  if (endTimestamp - startTimestamp < minimumAnimationTime) {
-                    autosaveTimeout = setTimeout(
-                      () => {
-                        setSaving(false)
-                      },
-                      minimumAnimationTime - (endTimestamp - startTimestamp),
-                    )
-                  } else {
-                    setSaving(false)
-                  }
+              if (res.status === 200) {
+                setLastUpdateTime(newDate.getTime())
+
+                reportUpdate({
+                  id,
+                  entitySlug,
+                  updatedAt: newDate.toISOString(),
                 })
+
+                if (!mostRecentVersionIsAutosaved) {
+                  incrementVersionCount()
+                  setMostRecentVersionIsAutosaved(true)
+                  setUnpublishedVersionCount((prev) => prev + 1)
+                }
+              }
+              const json = await res.json()
+
+              if (versionsConfig?.drafts && versionsConfig?.drafts?.validate && json?.errors) {
+                if (Array.isArray(json.errors)) {
+                  const [fieldErrors, nonFieldErrors] = json.errors.reduce(
+                    ([fieldErrs, nonFieldErrs], err) => {
+                      const newFieldErrs = []
+                      const newNonFieldErrs = []
+
+                      if (err?.message) {
+                        newNonFieldErrs.push(err)
+                      }
+
+                      if (Array.isArray(err?.data)) {
+                        err.data.forEach((dataError) => {
+                          if (dataError?.field) {
+                            newFieldErrs.push(dataError)
+                          } else {
+                            newNonFieldErrs.push(dataError)
+                          }
+                        })
+                      }
+
+                      return [
+                        [...fieldErrs, ...newFieldErrs],
+                        [...nonFieldErrs, ...newNonFieldErrs],
+                      ]
+                    },
+                    [[], []],
+                  )
+
+                  dispatchFields({
+                    type: 'ADD_SERVER_ERRORS',
+                    errors: fieldErrors,
+                  })
+
+                  nonFieldErrors.forEach((err) => {
+                    toast.error(err.message || i18n.t('error:unknown'))
+                  })
+
+                  // Set valid to false internally so the queue doesn't process
+                  isValidRef.current = false
+                  setIsValid(false)
+                  setSubmitted(true)
+                  hideIndicator()
+                  return
+                }
+              } else {
+                // If it's not an error then we can update the document data inside the context
+                const document = json?.doc || json?.result
+
+                // Manually update the data since this function doesn't fire the `submit` function from useForm
+                if (document) {
+                  setIsValid(true)
+
+                  // Reset internal state allowing the queue to process
+                  isValidRef.current = true
+                  updateSavedDocumentData(document)
+                }
+              }
+
+              hideIndicator()
             }
           }
         }
@@ -284,29 +288,50 @@ export const Autosave: React.FC<Props> = ({ id, collection, global: globalDoc })
 
     queueRef.current.push(autosave)
     void processQueue()
-
-    return { abortController, autosaveTimeout }
   })
 
+  const didMount = useRef(false)
+  const previousDebouncedFieldValues = useRef(reduceFieldsToValues(debouncedFields))
   // When debounced fields change, autosave
   useEffect(() => {
-    const { abortController, autosaveTimeout } = handleAutosave()
+    /**
+     * Ensure autosave doesn't run on mount
+     */
+    if (!didMount.current) {
+      didMount.current = true
+      return
+    }
 
-    return () => {
-      if (autosaveTimeout) {
-        clearTimeout(autosaveTimeout)
-      }
-      if (abortController.signal) {
-        try {
-          abortController.abort('Autosave closed early.')
-        } catch (error) {
-          // swallow error
-        }
-      }
-      setSaving(false)
+    /**
+     * Ensure autosave only runs if the form data changes, not every time the entire form state changes
+     */
+    const debouncedFieldValues = reduceFieldsToValues(debouncedFields)
+    if (dequal(debouncedFieldValues, previousDebouncedFieldValues)) {
+      return
     }
+
+    previousDebouncedFieldValues.current = debouncedFieldValues
+
+    handleAutosave()
   }, [debouncedFields])
 
+  /**
+   * If component unmounts, clear the autosave timeout
+   */
+  useEffect(() => {
+    return () => {
+      stopAutoSaveIndicator()
+    }
+  }, [])
+
+  const stopAutoSaveIndicator = useEffectEvent(() => {
+    if (autosaveTimeoutRef.current) {
+      clearTimeout(autosaveTimeoutRef.current)
+    }
+
+    setSaving(false)
+  })
+
   return (
     <div className={baseClass}>
       {validateOnDraft && !isValid && <LeaveWithoutSaving />}

packages/ui/src/forms/Form/index.tsx

@@ -446,6 +446,7 @@ export const Form: React.FC<FormProps> = (props) => {
     },
     [
       beforeSubmit,
+      startRouteTransition,
       action,
       disableSuccessStatus,
       disableValidationOnSubmit,