@tanstack/form-core 0.28.0 → 0.30.0

package/src/FormApi.ts

@@ -12,6 +12,7 @@ import type { Updater } from './utils'
 import type { DeepKeys, DeepValue } from './util-types'
 import type { FieldApi, FieldMeta } from './FieldApi'
 import type {
+  FormValidationError,
   UpdateMetaOptions,
   ValidationCause,
   ValidationError,
@@ -20,16 +21,17 @@ import type {
   Validator,
 } from './types'
 
-/**
- * @private
- */
+export type FieldsErrorMapFromValidator<TFormData> = Partial<
+  Record<DeepKeys<TFormData>, ValidationErrorMap>
+>
+
 export type FormValidateFn<
   TFormData,
   TFormValidator extends Validator<TFormData, unknown> | undefined = undefined,
 > = (props: {
   value: TFormData
   formApi: FormApi<TFormData, TFormValidator>
-}) => ValidationError
+}) => FormValidationError<TFormData>
 
 /**
  * @private
@@ -52,7 +54,22 @@ export type FormValidateAsyncFn<
   value: TFormData
   formApi: FormApi<TFormData, TFormValidator>
   signal: AbortSignal
-}) => ValidationError | Promise<ValidationError>
+}) => FormValidationError<TFormData> | Promise<FormValidationError<TFormData>>
+
+export type FormValidator<TFormData, TType, TFn = unknown> = {
+  validate(options: { value: TType }, fn: TFn): ValidationError
+  validateAsync(
+    options: { value: TType },
+    fn: TFn,
+  ): Promise<FormValidationError<TFormData>>
+}
+
+type ValidationPromiseResult<TFormData> =
+  | {
+      fieldErrors: Partial<Record<DeepKeys<TFormData>, ValidationError>>
+      errorMapKey: ValidationErrorMapKeys
+    }
+  | undefined
 
 /**
  * @private
@@ -86,11 +103,11 @@ export interface FormValidators<
    */
   onChangeAsyncDebounceMs?: number
   /**
-   * Optional function that validates the form data when a field loses focus, returns a ValidationError
+   * Optional function that validates the form data when a field loses focus, returns a `FormValidationError`
    */
   onBlur?: FormValidateOrFn<TFormData, TFormValidator>
   /**
-   * Optional onBlur asynchronous validation method for when a field loses focus return a `ValidationError` or a promise of `Promise<ValidationError>`
+   * Optional onBlur asynchronous validation method for when a field loses focus returns a ` FormValidationError` or a promise of `Promise<FormValidationError>`
    */
   onBlurAsync?: FormAsyncValidateOrFn<TFormData, TFormValidator>
   /**
@@ -606,35 +623,68 @@ export class FormApi<
    * TODO: This code is copied from FieldApi, we should refactor to share
    * @private
    */
-  validateSync = (cause: ValidationCause) => {
+  validateSync = (
+    cause: ValidationCause,
+  ): {
+    hasErrored: boolean
+    fieldsErrorMap: FieldsErrorMapFromValidator<TFormData>
+  } => {
     const validates = getSyncValidatorArray(cause, this.options)
     let hasErrored = false as boolean
 
+    const fieldsErrorMap: FieldsErrorMapFromValidator<TFormData> = {}
+
     this.store.batch(() => {
       for (const validateObj of validates) {
         if (!validateObj.validate) continue
 
-        const error = normalizeError(
-          this.runValidator({
-            validate: validateObj.validate,
-            value: {
-              value: this.state.values,
-              formApi: this,
-            },
-            type: 'validate',
-          }),
-        )
+        const rawError = this.runValidator({
+          validate: validateObj.validate,
+          value: {
+            value: this.state.values,
+            formApi: this,
+          },
+          type: 'validate',
+        })
+
+        const { formError, fieldErrors } = normalizeError<TFormData>(rawError)
+
         const errorMapKey = getErrorMapKey(validateObj.cause)
-        if (this.state.errorMap[errorMapKey] !== error) {
+
+        if (fieldErrors) {
+          for (const [field, fieldError] of Object.entries(fieldErrors)) {
+            const oldErrorMap =
+              fieldsErrorMap[field as DeepKeys<TFormData>] || {}
+            const newErrorMap = {
+              ...oldErrorMap,
+              [errorMapKey]: fieldError,
+            }
+            fieldsErrorMap[field as DeepKeys<TFormData>] = newErrorMap
+
+            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 (this.state.errorMap[errorMapKey] !== formError) {
           this.store.setState((prev) => ({
             ...prev,
             errorMap: {
               ...prev.errorMap,
-              [errorMapKey]: error,
+              [errorMapKey]: formError,
             },
           }))
         }
-        if (error) {
+
+        if (formError || fieldErrors) {
           hasErrored = true
         }
       }
@@ -659,7 +709,7 @@ export class FormApi<
       }))
     }
 
-    return { hasErrored }
+    return { hasErrored, fieldsErrorMap }
   }
 
   /**
@@ -667,7 +717,7 @@ export class FormApi<
    */
   validateAsync = async (
     cause: ValidationCause,
-  ): Promise<ValidationError[]> => {
+  ): Promise<FieldsErrorMapFromValidator<TFormData>> => {
     const validates = getAsyncValidatorArray(cause, this.options)
 
     if (!this.state.isFormValidating) {
@@ -678,7 +728,11 @@ export class FormApi<
      * We have to use a for loop and generate our promises this way, otherwise it won't be sync
      * when there are no validators needed to be run
      */
-    const promises: Promise<ValidationError | undefined>[] = []
+    const promises: Promise<ValidationPromiseResult<TFormData>>[] = []
+
+    let fieldErrors:
+      | Partial<Record<DeepKeys<TFormData>, ValidationError>>
+      | undefined
 
     for (const validateObj of validates) {
       if (!validateObj.validate) continue
@@ -693,7 +747,7 @@ export class FormApi<
       }
 
       promises.push(
-        new Promise<ValidationError | undefined>(async (resolve) => {
+        new Promise<ValidationPromiseResult<TFormData>>(async (resolve) => {
           let rawError!: ValidationError | undefined
           try {
             rawError = await new Promise((rawResolve, rawReject) => {
@@ -719,23 +773,65 @@ export class FormApi<
           } catch (e: unknown) {
             rawError = e as ValidationError
           }
-          const error = normalizeError(rawError)
+          const { formError, fieldErrors: fieldErrorsFromNormalizeError } =
+            normalizeError<TFormData>(rawError)
+
+          if (fieldErrorsFromNormalizeError) {
+            fieldErrors = fieldErrors
+              ? { ...fieldErrors, ...fieldErrorsFromNormalizeError }
+              : fieldErrorsFromNormalizeError
+          }
+          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,
+                  },
+                }))
+              }
+            }
+          }
           this.store.setState((prev) => ({
             ...prev,
             errorMap: {
               ...prev.errorMap,
-              [getErrorMapKey(cause)]: error,
+              [errorMapKey]: formError,
             },
           }))
 
-          resolve(error)
+          resolve(fieldErrors ? { fieldErrors, errorMapKey } : undefined)
         }),
       )
     }
 
-    let results: ValidationError[] = []
+    let results: ValidationPromiseResult<TFormData>[] = []
+
+    const fieldsErrorMap: FieldsErrorMapFromValidator<TFormData> = {}
     if (promises.length) {
       results = await Promise.all(promises)
+      for (const fieldValidationResult of results) {
+        if (fieldValidationResult?.fieldErrors) {
+          const { errorMapKey } = fieldValidationResult
+
+          for (const [field, fieldError] of Object.entries(
+            fieldValidationResult.fieldErrors,
+          )) {
+            const oldErrorMap =
+              fieldsErrorMap[field as DeepKeys<TFormData>] || {}
+            const newErrorMap = {
+              ...oldErrorMap,
+              [errorMapKey]: fieldError,
+            }
+            fieldsErrorMap[field as DeepKeys<TFormData>] = newErrorMap
+          }
+        }
+      }
     }
 
     this.store.setState((prev) => ({
@@ -743,7 +839,7 @@ export class FormApi<
       isFormValidating: false,
     }))
 
-    return results.filter(Boolean)
+    return fieldsErrorMap
   }
 
   /**
@@ -751,12 +847,14 @@ export class FormApi<
    */
   validate = (
     cause: ValidationCause,
-  ): ValidationError[] | Promise<ValidationError[]> => {
+  ):
+    | FieldsErrorMapFromValidator<TFormData>
+    | Promise<FieldsErrorMapFromValidator<TFormData>> => {
     // Attempt to sync validate first
-    const { hasErrored } = this.validateSync(cause)
+    const { hasErrored, fieldsErrorMap } = this.validateSync(cause)
 
     if (hasErrored && !this.options.asyncAlways) {
-      return this.state.errors
+      return fieldsErrorMap
     }
 
     // No error? Attempt async validation
@@ -1109,16 +1207,25 @@ export class FormApi<
   }
 }
 
-function normalizeError(rawError?: ValidationError) {
+function normalizeError<TFormData>(rawError?: FormValidationError<TFormData>): {
+  formError: ValidationError
+  fieldErrors?: Partial<Record<DeepKeys<TFormData>, ValidationError>>
+} {
   if (rawError) {
+    if (typeof rawError === 'object') {
+      const formError = normalizeError(rawError.form).formError
+      const fieldErrors = rawError.fields
+      return { formError, fieldErrors }
+    }
+
     if (typeof rawError !== 'string') {
-      return 'Invalid Form Values'
+      return { formError: 'Invalid Form Values' }
     }
 
-    return rawError
+    return { formError: rawError }
   }
 
-  return undefined
+  return { formError: undefined }
 }
 
 function getErrorMapKey(cause: ValidationCause) {

package/src/types.ts

@@ -1,3 +1,5 @@
+import { type DeepKeys } from './util-types'
+
 export type ValidationError = undefined | false | null | string
 
 /**
@@ -9,6 +11,14 @@ export type Validator<Type, Fn = unknown> = () => {
   validateAsync(options: { value: Type }, fn: Fn): Promise<ValidationError>
 }
 
+/**
+ * Parameters in common for all validator adapters, making it easier to swap adapter
+ * @private
+ */
+export type ValidatorAdapterParams<TError = unknown> = {
+  transformErrors?: (errors: TError[]) => ValidationError
+}
+
 /**
  * "server" is only intended for SSR/SSG validation and should not execute anything
  * @private
@@ -27,6 +37,26 @@ export type ValidationErrorMap = {
   [K in ValidationErrorMapKeys]?: ValidationError
 }
 
+/**
+ * @private
+ *
+ * @example
+ * ```tsx
+ * {
+ *   form: 'This form contains an error',
+ *   fields: {
+ *     age: "Must be 13 or older to register"
+ *   }
+ * }
+ * ````
+ */
+export type FormValidationError<TFormData> =
+  | ValidationError
+  | {
+      form?: ValidationError
+      fields: Partial<Record<DeepKeys<TFormData>, ValidationError>>
+    }
+
 /**
  * @private
  */