fix(form-core): fix broken sync/async validation logic

This commit updates async validators to ensure source map is synced with full coverage.

Fixes "Cannot read properties of undefined" when removing array field #1323

Author: juanvilladev

Diff for: packages/form-core/src/FieldApi.ts

@@ -24,6 +24,7 @@ import type {
   ValidationCause,
   ValidationError,
   ValidationErrorMap,
+  ValidationErrorMapSource,
 } from './types'
 import type { AsyncValidator, SyncValidator, Updater } from './utils'
 
@@ -561,6 +562,10 @@ export type FieldMetaBase<
       TFormOnSubmitAsync
     >
   >
+  /**
+   * @private allows tracking the source of the errors in the error map
+   */
+  errorSourceMap: ValidationErrorMapSource
   /**
    * A flag indicating whether the field is currently being validated.
    */
@@ -1096,6 +1101,11 @@ export class FieldApi<
               ...prev,
               // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
               errorMap: { ...prev?.errorMap, onMount: error },
+              errorSourceMap: {
+                // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+                ...prev?.errorSourceMap,
+                onMount: 'field',
+              },
             }) as never,
         )
       }
@@ -1389,6 +1399,14 @@ export class FieldApi<
                 // Prefer the error message from the field validators if they exist
                 error ? error : errorFromForm[errorMapKey],
             },
+            errorSourceMap: {
+              ...prev.errorSourceMap,
+              [getErrorMapKey(validateObj.cause)]: error
+                ? 'field'
+                : errorFromForm[errorMapKey]
+                  ? 'form'
+                  : undefined,
+            },
           }))
         }
         if (error || errorFromForm[errorMapKey]) {
@@ -1422,6 +1440,10 @@ export class FieldApi<
           ...prev.errorMap,
           [submitErrKey]: undefined,
         },
+        errorSourceMap: {
+          ...prev.errorSourceMap,
+          [submitErrKey]: undefined,
+        },
       }))
     }
 
@@ -1544,6 +1566,14 @@ export class FieldApi<
                 ...prev?.errorMap,
                 [errorMapKey]: fieldError,
               },
+              errorSourceMap: {
+                ...prev.errorSourceMap,
+                [errorMapKey]: error
+                  ? 'field'
+                  : fieldErrorFromForm
+                    ? 'form'
+                    : undefined,
+              },
             }
           })
 

Diff for: packages/form-core/src/FormApi.ts

@@ -1,6 +1,7 @@
 import { Derived, Store, batch } from '@tanstack/store'
 import {
   deleteBy,
+  determineErrorValue,
   functionalUpdate,
   getAsyncValidatorArray,
   getBy,
@@ -729,22 +730,6 @@ export class FormApi<
    */
   prevTransformArray: unknown[] = []
 
-  /**
-   * @private Persistent store of all field validation errors originating from form-level validators.
-   * Maintains the cumulative state across validation cycles, including cleared errors (undefined values).
-   * This map preserves the complete validation state for all fields.
-   */
-  cumulativeFieldsErrorMap: FormErrorMapFromValidator<
-    TFormData,
-    TOnMount,
-    TOnChange,
-    TOnChangeAsync,
-    TOnBlur,
-    TOnBlurAsync,
-    TOnSubmit,
-    TOnSubmitAsync
-  > = {}
-
   /**
    * Constructs a new `FormApi` instance with the given form options.
    */
@@ -1300,50 +1285,48 @@ export class FormApi<
 
         const errorMapKey = getErrorMapKey(validateObj.cause)
 
-        if (fieldErrors) {
-          for (const [field, fieldError] of Object.entries(fieldErrors) as [
-            DeepKeys<TFormData>,
-            ValidationError,
-          ][]) {
-            const oldErrorMap = this.cumulativeFieldsErrorMap[field] || {}
-            const newErrorMap = {
-              ...oldErrorMap,
-              [errorMapKey]: fieldError,
-            }
-            currentValidationErrorMap[field] = newErrorMap
-            this.cumulativeFieldsErrorMap[field] = newErrorMap
+        for (const field of Object.keys(
+          this.state.fieldMeta,
+        ) as DeepKeys<TFormData>[]) {
+          const fieldMeta = this.getFieldMeta(field)
+          if (!fieldMeta) continue
 
-            const fieldMeta = this.getFieldMeta(field)
-            if (fieldMeta && fieldMeta.errorMap[errorMapKey] !== fieldError) {
-              this.setFieldMeta(field, (prev) => ({
-                ...prev,
-                errorMap: {
-                  ...prev.errorMap,
-                  [errorMapKey]: fieldError,
-                },
-              }))
+          const {
+            errorMap: currentErrorMap,
+            errorSourceMap: currentErrorMapSource,
+          } = fieldMeta
+
+          const newFormValidatorError = fieldErrors?.[field]
+
+          const { newErrorValue, newSource } = determineErrorValue({
+            newFormValidatorError,
+            isPreviousErrorFromFormValidator:
+              // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+              currentErrorMapSource?.[errorMapKey] === 'form',
+            // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+            previousErrorValue: currentErrorMap?.[errorMapKey],
+          })
+
+          if (newSource === 'form') {
+            currentValidationErrorMap[field] = {
+              ...currentValidationErrorMap[field],
+              [errorMapKey]: newFormValidatorError,
             }
           }
-        }
 
-        for (const field of Object.keys(this.cumulativeFieldsErrorMap) as Array<
-          DeepKeys<TFormData>
-        >) {
-          const fieldMeta = this.getFieldMeta(field)
           if (
-            fieldMeta?.errorMap[errorMapKey] &&
-            !currentValidationErrorMap[field]?.[errorMapKey]
+            // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+            currentErrorMap?.[errorMapKey] !== newErrorValue
           ) {
-            this.cumulativeFieldsErrorMap[field] = {
-              ...this.cumulativeFieldsErrorMap[field],
-              [errorMapKey]: undefined,
-            }
-
             this.setFieldMeta(field, (prev) => ({
               ...prev,
               errorMap: {
                 ...prev.errorMap,
-                [errorMapKey]: undefined,
+                [errorMapKey]: newErrorValue,
+              },
+              errorSourceMap: {
+                ...prev.errorSourceMap,
+                [errorMapKey]: newSource,
               },
             }))
           }
@@ -1473,20 +1456,47 @@ export class FormApi<
           }
           const errorMapKey = getErrorMapKey(validateObj.cause)
 
-          if (fieldErrors) {
-            for (const [field, fieldError] of Object.entries(fieldErrors)) {
-              const fieldMeta = this.getFieldMeta(field as DeepKeys<TFormData>)
-              if (fieldMeta && fieldMeta.errorMap[errorMapKey] !== fieldError) {
-                this.setFieldMeta(field as DeepKeys<TFormData>, (prev) => ({
-                  ...prev,
-                  errorMap: {
-                    ...prev.errorMap,
-                    [errorMapKey]: fieldError,
-                  },
-                }))
-              }
+          // if (fieldErrors) {
+          for (const field of Object.keys(
+            this.state.fieldMeta,
+          ) as DeepKeys<TFormData>[]) {
+            const fieldMeta = this.getFieldMeta(field)
+            if (!fieldMeta) continue
+
+            const {
+              errorMap: currentErrorMap,
+              errorSourceMap: currentErrorMapSource,
+            } = fieldMeta
+
+            const newFormValidatorError = fieldErrors?.[field]
+
+            const { newErrorValue, newSource } = determineErrorValue({
+              newFormValidatorError,
+              isPreviousErrorFromFormValidator:
+                // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+                currentErrorMapSource?.[errorMapKey] === 'form',
+              // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+              previousErrorValue: currentErrorMap?.[errorMapKey],
+            })
+
+            if (
+              // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+              currentErrorMap?.[errorMapKey] !== newErrorValue
+            ) {
+              this.setFieldMeta(field, (prev) => ({
+                ...prev,
+                errorMap: {
+                  ...prev.errorMap,
+                  [errorMapKey]: newErrorValue,
+                },
+                errorSourceMap: {
+                  ...prev.errorSourceMap,
+                  [errorMapKey]: newSource,
+                },
+              }))
             }
           }
+
           this.baseStore.setState((prev) => ({
             ...prev,
             errorMap: {

Diff for: packages/form-core/src/metaHelper.ts

@@ -16,6 +16,7 @@ export const defaultFieldMeta: AnyFieldMeta = {
   isPristine: true,
   errors: [],
   errorMap: {},
+  errorSourceMap: {},
 }
 
 export function metaHelper<

Diff for: packages/form-core/src/types.ts

@@ -28,16 +28,39 @@ export type ValidationErrorMap<
   TOnSubmitAsyncReturn = unknown,
   TOnServerReturn = unknown,
 > = {
-  onMount?: TOnMountReturn
-  onChange?: TOnChangeReturn | TOnChangeAsyncReturn
-  onBlur?: TOnBlurReturn | TOnBlurAsyncReturn
-  onSubmit?: TOnSubmitReturn | TOnSubmitAsyncReturn
-  onServer?: TOnServerReturn
+  onMount?: {
+    error: TOnMountReturn
+    source: ValidationSource
+  }
+  onChange?: {
+    error: TOnChangeReturn | TOnChangeAsyncReturn
+    source: ValidationSource
+  }
+  onBlur?: {
+    error: TOnBlurReturn | TOnBlurAsyncReturn
+    source: ValidationSource
+  }
+  onSubmit?: {
+    error: TOnSubmitReturn | TOnSubmitAsyncReturn
+    source: ValidationSource
+  }
+  onServer?: {
+    error: TOnServerReturn
+    source: ValidationSource
+  }
 }
 
 /**
- * @private
+ * @private allows tracking the source of the errors in the error map
  */
+export type ValidationErrorMapSource = {
+  onMount?: ValidationSource
+  onChange?: ValidationSource
+  onBlur?: ValidationSource
+  onSubmit?: ValidationSource
+  onServer?: ValidationSource
+}
+
 export type FormValidationErrorMap<
   TOnMountReturn = unknown,
   TOnChangeReturn = unknown,

Diff for: packages/form-core/src/utils.ts

@@ -1,4 +1,8 @@
-import type { GlobalFormValidationError, ValidationCause } from './types'
+import type {
+  GlobalFormValidationError,
+  ValidationCause,
+  ValidationError,
+} from './types'
 import type { FormValidators } from './FormApi'
 import type { AnyFieldMeta, FieldValidators } from './FieldApi'
 
@@ -376,3 +380,30 @@ export function shallow<T>(objA: T, objB: T) {
   }
   return true
 }
+
+/**
+ * Determines the logic for determining the error value to set on the field meta within the form sync validation.
+ * @private
+ */
+export const determineErrorValue = ({
+  newFormValidatorError,
+  isPreviousErrorFromFormValidator,
+  previousErrorValue,
+}: {
+  newFormValidatorError: ValidationError
+  isPreviousErrorFromFormValidator: boolean
+  previousErrorValue: ValidationError
+}) => {
+  // All falsy values are not considered errors
+  if (newFormValidatorError) {
+    return { newErrorValue: newFormValidatorError, newSource: 'form' }
+  }
+
+  // Clears form level error since it's now stale
+  if (isPreviousErrorFromFormValidator) {
+    return { newErrorValue: undefined, newSource: undefined }
+  }
+
+  // Do not clear field level validators since they're handled by the field validator
+  return { newErrorValue: previousErrorValue, newSource: 'field' }
+}

Diff for: packages/form-core/tests/FieldApi.spec.ts

@@ -61,6 +61,7 @@ describe('field api', () => {
       isDirty: false,
       errors: [],
       errorMap: {},
+      errorSourceMap: {},
     })
   })
 
@@ -90,6 +91,7 @@ describe('field api', () => {
       isPristine: false,
       errors: [],
       errorMap: {},
+      errorSourceMap: {},
     })
   })
 
@@ -1890,4 +1892,30 @@ describe('field api', () => {
     expect(field.getMeta().errors).toStrictEqual([])
     expect(form.state.canSubmit).toBe(true)
   })
+
+  it('should update the errorSourceMap with field source when field async field error is added', async () => {
+    vi.useFakeTimers()
+    const form = new FormApi({
+      defaultValues: {
+        name: 'test',
+      },
+    })
+    form.mount()
+
+    const field = new FieldApi({
+      form,
+      name: 'name',
+      validators: {
+        onChangeAsync: async () => {
+          return 'Error'
+        },
+      },
+    })
+    field.mount()
+
+    field.setValue('test')
+    await vi.runAllTimersAsync()
+
+    expect(field.getMeta().errorSourceMap.onChange).toEqual('field')
+  })
 })