@tanstack/form-core 0.10.3 → 0.12.0

package/src/FieldApi.ts

@@ -1,115 +1,209 @@
 import { Store } from '@tanstack/store'
-import type { FormApi, ValidationErrorMap } from './FormApi'
-import type { ValidationError, Validator } from './types'
+import type { FormApi } from './FormApi'
+import type {
+  ValidationCause,
+  ValidationError,
+  ValidationErrorMap,
+  Validator,
+} from './types'
 import type { DeepKeys, DeepValue, Updater } from './utils'
+import { getAsyncValidatorArray, getSyncValidatorArray } from './utils'
 
-export type ValidationCause = 'change' | 'blur' | 'submit' | 'mount'
-
-type ValidateFn<
+export type FieldValidateFn<
   TParentData,
   TName extends DeepKeys<TParentData>,
-  ValidatorType,
+  TFieldValidator extends
+    | Validator<DeepValue<TParentData, TName>, unknown>
+    | undefined = undefined,
+  TFormValidator extends
+    | Validator<TParentData, unknown>
+    | undefined = undefined,
   TData extends DeepValue<TParentData, TName> = DeepValue<TParentData, TName>,
-> = (
-  value: TData,
-  fieldApi: FieldApi<TParentData, TName, ValidatorType, TData>,
-) => ValidationError
+> = (props: {
+  value: TData
+  fieldApi: FieldApi<TParentData, TName, TFieldValidator, TFormValidator, TData>
+}) => ValidationError
 
-type ValidateOrFn<
+export type FieldValidateOrFn<
   TParentData,
   TName extends DeepKeys<TParentData>,
-  ValidatorType,
-  FormValidator,
+  TFieldValidator extends
+    | Validator<DeepValue<TParentData, TName>, unknown>
+    | undefined = undefined,
+  TFormValidator extends
+    | Validator<TParentData, unknown>
+    | undefined = undefined,
   TData extends DeepValue<TParentData, TName> = DeepValue<TParentData, TName>,
-> = ValidatorType extends Validator<TData>
+> = TFieldValidator extends Validator<TData, infer TFN>
   ?
-      | Parameters<ReturnType<ValidatorType>['validate']>[1]
-      | ValidateFn<TParentData, TName, ValidatorType, TData>
-  : FormValidator extends Validator<TData>
-  ?
-      | Parameters<ReturnType<FormValidator>['validate']>[1]
-      | ValidateFn<TParentData, TName, ValidatorType, TData>
-  : ValidateFn<TParentData, TName, ValidatorType, TData>
-
-type ValidateAsyncFn<
+      | TFN
+      | FieldValidateFn<
+          TParentData,
+          TName,
+          TFieldValidator,
+          TFormValidator,
+          TData
+        >
+  : TFormValidator extends Validator<TParentData, infer FFN>
+    ?
+        | FFN
+        | FieldValidateFn<
+            TParentData,
+            TName,
+            TFieldValidator,
+            TFormValidator,
+            TData
+          >
+    : FieldValidateFn<
+        TParentData,
+        TName,
+        TFieldValidator,
+        TFormValidator,
+        TData
+      >
+
+export type FieldValidateAsyncFn<
   TParentData,
   TName extends DeepKeys<TParentData>,
-  ValidatorType,
+  TFieldValidator extends
+    | Validator<DeepValue<TParentData, TName>, unknown>
+    | undefined = undefined,
+  TFormValidator extends
+    | Validator<TParentData, unknown>
+    | undefined = undefined,
   TData extends DeepValue<TParentData, TName> = DeepValue<TParentData, TName>,
-> = (
-  value: TData,
-  fieldApi: FieldApi<TParentData, TName, ValidatorType, TData>,
-) => ValidationError | Promise<ValidationError>
+> = (options: {
+  value: TData
+  fieldApi: FieldApi<TParentData, TName, TFieldValidator, TFormValidator, TData>
+  signal: AbortSignal
+}) => ValidationError | Promise<ValidationError>
 
-type AsyncValidateOrFn<
+export type FieldAsyncValidateOrFn<
   TParentData,
   TName extends DeepKeys<TParentData>,
-  ValidatorType,
-  FormValidator,
+  TFieldValidator extends
+    | Validator<DeepValue<TParentData, TName>, unknown>
+    | undefined = undefined,
+  TFormValidator extends
+    | Validator<TParentData, unknown>
+    | undefined = undefined,
   TData extends DeepValue<TParentData, TName> = DeepValue<TParentData, TName>,
-> = ValidatorType extends Validator<TData>
-  ?
-      | Parameters<ReturnType<ValidatorType>['validate']>[1]
-      | ValidateAsyncFn<TParentData, TName, ValidatorType, TData>
-  : FormValidator extends Validator<TData>
+> = TFieldValidator extends Validator<TData, infer TFN>
   ?
-      | Parameters<ReturnType<FormValidator>['validate']>[1]
-      | ValidateAsyncFn<TParentData, TName, ValidatorType, TData>
-  : ValidateAsyncFn<TParentData, TName, ValidatorType, TData>
-
-export interface FieldOptions<
+      | TFN
+      | FieldValidateAsyncFn<
+          TParentData,
+          TName,
+          TFieldValidator,
+          TFormValidator,
+          TData
+        >
+  : TFormValidator extends Validator<TParentData, infer FFN>
+    ?
+        | FFN
+        | FieldValidateAsyncFn<
+            TParentData,
+            TName,
+            TFieldValidator,
+            TFormValidator,
+            TData
+          >
+    : FieldValidateAsyncFn<
+        TParentData,
+        TName,
+        TFieldValidator,
+        TFormValidator,
+        TData
+      >
+
+export interface FieldValidators<
   TParentData,
   TName extends DeepKeys<TParentData>,
-  ValidatorType,
-  FormValidator,
+  TFieldValidator extends
+    | Validator<DeepValue<TParentData, TName>, unknown>
+    | undefined = undefined,
+  TFormValidator extends
+    | Validator<TParentData, unknown>
+    | undefined = undefined,
   TData extends DeepValue<TParentData, TName> = DeepValue<TParentData, TName>,
 > {
-  name: TName
-  index?: TData extends any[] ? number : never
-  defaultValue?: TData
-  asyncDebounceMs?: number
-  asyncAlways?: boolean
-  preserveValue?: boolean
-  validator?: ValidatorType
-  onMount?: (
-    formApi: FieldApi<TParentData, TName, ValidatorType, TData>,
-  ) => void
-  onChange?: ValidateOrFn<
+  onMount?: FieldValidateOrFn<
     TParentData,
     TName,
-    ValidatorType,
-    FormValidator,
+    TFieldValidator,
+    TFormValidator,
     TData
   >
-  onChangeAsync?: AsyncValidateOrFn<
+  onChange?: FieldValidateOrFn<
     TParentData,
     TName,
-    ValidatorType,
-    FormValidator,
+    TFieldValidator,
+    TFormValidator,
+    TData
+  >
+  onChangeAsync?: FieldAsyncValidateOrFn<
+    TParentData,
+    TName,
+    TFieldValidator,
+    TFormValidator,
     TData
   >
   onChangeAsyncDebounceMs?: number
-  onBlur?: ValidateOrFn<TParentData, TName, ValidatorType, FormValidator, TData>
-  onBlurAsync?: AsyncValidateOrFn<
+  onBlur?: FieldValidateOrFn<
     TParentData,
     TName,
-    ValidatorType,
-    FormValidator,
+    TFieldValidator,
+    TFormValidator,
+    TData
+  >
+  onBlurAsync?: FieldAsyncValidateOrFn<
+    TParentData,
+    TName,
+    TFieldValidator,
+    TFormValidator,
     TData
   >
   onBlurAsyncDebounceMs?: number
-  onSubmit?: ValidateOrFn<
+  onSubmit?: FieldValidateOrFn<
+    TParentData,
+    TName,
+    TFieldValidator,
+    TFormValidator,
+    TData
+  >
+  onSubmitAsync?: FieldAsyncValidateOrFn<
     TParentData,
     TName,
-    ValidatorType,
-    FormValidator,
+    TFieldValidator,
+    TFormValidator,
     TData
   >
-  onSubmitAsync?: AsyncValidateOrFn<
+  onSubmitAsyncDebounceMs?: number
+}
+
+export interface FieldOptions<
+  TParentData,
+  TName extends DeepKeys<TParentData>,
+  TFieldValidator extends
+    | Validator<DeepValue<TParentData, TName>, unknown>
+    | undefined = undefined,
+  TFormValidator extends
+    | Validator<TParentData, unknown>
+    | undefined = undefined,
+  TData extends DeepValue<TParentData, TName> = DeepValue<TParentData, TName>,
+> {
+  name: TName
+  index?: TData extends any[] ? number : never
+  defaultValue?: TData
+  asyncDebounceMs?: number
+  asyncAlways?: boolean
+  preserveValue?: boolean
+  validatorAdapter?: TFieldValidator
+  validators?: FieldValidators<
     TParentData,
     TName,
-    ValidatorType,
-    FormValidator,
+    TFieldValidator,
+    TFormValidator,
     TData
   >
   defaultMeta?: Partial<FieldMeta>
@@ -118,17 +212,21 @@ export interface FieldOptions<
 export interface FieldApiOptions<
   TParentData,
   TName extends DeepKeys<TParentData>,
-  ValidatorType,
-  FormValidator,
+  TFieldValidator extends
+    | Validator<DeepValue<TParentData, TName>, unknown>
+    | undefined = undefined,
+  TFormValidator extends
+    | Validator<TParentData, unknown>
+    | undefined = undefined,
   TData extends DeepValue<TParentData, TName> = DeepValue<TParentData, TName>,
 > extends FieldOptions<
     TParentData,
     TName,
-    ValidatorType,
-    FormValidator,
+    TFieldValidator,
+    TFormValidator,
     TData
   > {
-  form: FormApi<TParentData, FormValidator>
+  form: FormApi<TParentData, TFormValidator>
 }
 
 export type FieldMeta = {
@@ -153,14 +251,30 @@ export type ResolveName<TParentData> = unknown extends TParentData
 export class FieldApi<
   TParentData,
   TName extends DeepKeys<TParentData>,
-  ValidatorType,
-  FormValidator,
+  TFieldValidator extends
+    | Validator<DeepValue<TParentData, TName>, unknown>
+    | undefined = undefined,
+  TFormValidator extends
+    | Validator<TParentData, unknown>
+    | undefined = undefined,
   TData extends DeepValue<TParentData, TName> = DeepValue<TParentData, TName>,
 > {
   uid: number
-  form: FieldApiOptions<TParentData, TName, ValidatorType, TData>['form']
+  form: FieldApiOptions<
+    TParentData,
+    TName,
+    TFieldValidator,
+    TFormValidator,
+    TData
+  >['form']
   name!: DeepKeys<TParentData>
-  options: FieldApiOptions<TParentData, TName, ValidatorType, TData> = {} as any
+  options: FieldApiOptions<
+    TParentData,
+    TName,
+    TFieldValidator,
+    TFormValidator,
+    TData
+  > = {} as any
   store!: Store<FieldState<TData>>
   state!: FieldState<TData>
   prevState!: FieldState<TData>
@@ -169,8 +283,8 @@ export class FieldApi<
     opts: FieldApiOptions<
       TParentData,
       TName,
-      ValidatorType,
-      FormValidator,
+      TFieldValidator,
+      TFormValidator,
       TData
     >,
   ) {
@@ -224,6 +338,29 @@ export class FieldApi<
     this.options = opts as never
   }
 
+  runValidator<
+    TValue extends { value: TData; fieldApi: FieldApi<any, any, any, any> },
+    TType extends 'validate' | 'validateAsync',
+  >(props: {
+    validate: TType extends 'validate'
+      ? FieldValidateOrFn<any, any, any, any>
+      : FieldAsyncValidateOrFn<any, any, any, any>
+    value: TValue
+    type: TType
+  }): ReturnType<ReturnType<Validator<any>>[TType]> {
+    const adapters = [
+      this.form.options.validatorAdapter,
+      this.options.validatorAdapter,
+    ] as const
+    for (const adapter of adapters) {
+      if (adapter && typeof props.validate !== 'function') {
+        return adapter()[props.type](props.value, props.validate) as never
+      }
+    }
+
+    return (props.validate as FieldValidateFn<any, any>)(props.value) as never
+  }
+
   mount = () => {
     const info = this.getInfo()
     info.instances[this.uid] = this as never
@@ -243,7 +380,25 @@ export class FieldApi<
     })
 
     this.update(this.options as never)
-    this.options.onMount?.(this as never)
+    const { onMount } = this.options.validators || {}
+
+    if (onMount) {
+      const error = this.runValidator({
+        validate: onMount,
+        value: {
+          value: this.state.value,
+          fieldApi: this,
+        },
+        type: 'validate',
+      })
+      if (error) {
+        this.setMeta((prev) => ({
+          ...prev,
+          // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+          errorMap: { ...prev?.errorMap, onMount: error },
+        }))
+      }
+    }
 
     return () => {
       const preserveValue = this.options.preserveValue
@@ -260,7 +415,13 @@ export class FieldApi<
   }
 
   update = (
-    opts: FieldApiOptions<TParentData, TName, ValidatorType, TData>,
+    opts: FieldApiOptions<
+      TParentData,
+      TName,
+      TFieldValidator,
+      TFormValidator,
+      TData
+    >,
   ) => {
     // Default Value
     // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
@@ -330,52 +491,20 @@ export class FieldApi<
     TSubData extends DeepValue<TData, TSubName> = DeepValue<TData, TSubName>,
   >(
     name: TSubName,
-  ): FieldApi<TData, TSubName, ValidatorType, TSubData> =>
+  ): FieldApi<
+    TData,
+    TSubName,
+    Validator<TSubData, unknown> | undefined,
+    Validator<TData, unknown> | undefined,
+    TSubData
+  > =>
     new FieldApi({
       name: `${this.name}.${name}` as never,
       form: this.form,
     }) as any
 
   validateSync = (value = this.state.value, cause: ValidationCause) => {
-    const { onChange, onBlur, onSubmit } = this.options
-
-    const validates =
-      // https://github.com/TanStack/form/issues/490
-      cause === 'submit'
-        ? ([
-            { cause: 'change', validate: onChange },
-            { cause: 'blur', validate: onBlur },
-            { cause: 'submit', validate: onSubmit },
-          ] as const)
-        : cause === 'change'
-        ? ([{ cause: 'change', validate: onChange }] as const)
-        : ([{ cause: 'blur', validate: onBlur }] as const)
-
-    // Use the validationCount for all field instances to
-    // track freshness of the validation
-    const validationCount = (this.getInfo().validationCount || 0) + 1
-    this.getInfo().validationCount = validationCount
-
-    const doValidate = (validate: (typeof validates)[number]['validate']) => {
-      if (this.options.validator && typeof validate !== 'function') {
-        return (this.options.validator as Validator<TData>)().validate(
-          value,
-          validate,
-        )
-      }
-
-      if (this.form.options.validator && typeof validate !== 'function') {
-        return (this.form.options.validator as Validator<TData>)().validate(
-          value,
-          validate,
-        )
-      }
-
-      return (validate as ValidateFn<TParentData, TName, ValidatorType, TData>)(
-        value,
-        this as never,
-      )
-    }
+    const validates = getSyncValidatorArray(cause, this.options)
 
     // Needs type cast as eslint errantly believes this is always falsy
     let hasErrored = false as boolean
@@ -383,7 +512,13 @@ export class FieldApi<
     this.form.store.batch(() => {
       for (const validateObj of validates) {
         if (!validateObj.validate) continue
-        const error = normalizeError(doValidate(validateObj.validate))
+        const error = normalizeError(
+          this.runValidator({
+            validate: validateObj.validate,
+            value: { value, fieldApi: this },
+            type: 'validate',
+          }),
+        )
         const errorMapKey = getErrorMapKey(validateObj.cause)
         if (this.state.meta.errorMap[errorMapKey] !== error) {
           this.setMeta((prev) => ({
@@ -419,130 +554,86 @@ export class FieldApi<
       }))
     }
 
-    // If a sync error is encountered for the errorMapKey (eg. onChange), cancel any async validation
-    if (hasErrored) {
-      this.cancelValidateAsync()
-    }
-
     return { hasErrored }
   }
 
-  __leaseValidateAsync = () => {
-    const count = (this.getInfo().validationAsyncCount || 0) + 1
-    this.getInfo().validationAsyncCount = count
-    return count
-  }
-
-  cancelValidateAsync = () => {
-    // Lease a new validation count to ignore any pending validations
-    this.__leaseValidateAsync()
-    // Cancel any pending validation state
-    this.setMeta((prev) => ({
-      ...prev,
-      isValidating: false,
-    }))
-  }
-
   validateAsync = async (value = this.state.value, cause: ValidationCause) => {
-    const {
-      onChangeAsync,
-      onBlurAsync,
-      onSubmitAsync,
-      asyncDebounceMs,
-      onBlurAsyncDebounceMs,
-      onChangeAsyncDebounceMs,
-    } = this.options
-
-    const validate =
-      cause === 'change'
-        ? onChangeAsync
-        : cause === 'submit'
-        ? onSubmitAsync
-        : onBlurAsync
-    if (!validate) return []
-    const debounceMs =
-      cause === 'submit'
-        ? 0
-        : (cause === 'change'
-            ? onChangeAsyncDebounceMs
-            : onBlurAsyncDebounceMs) ??
-          asyncDebounceMs ??
-          0
-
-    if (this.state.meta.isValidating !== true) {
+    const validates = getAsyncValidatorArray(cause, this.options)
+
+    if (!this.state.meta.isValidating) {
       this.setMeta((prev) => ({ ...prev, isValidating: true }))
     }
 
-    // Use the validationCount for all field instances to
-    // track freshness of the validation
-    const validationAsyncCount = this.__leaseValidateAsync()
-
-    const checkLatest = () =>
-      validationAsyncCount === this.getInfo().validationAsyncCount
-
-    if (!this.getInfo().validationPromise) {
-      this.getInfo().validationPromise = new Promise((resolve, reject) => {
-        this.getInfo().validationResolve = resolve
-        this.getInfo().validationReject = reject
-      })
-    }
+    /**
+     * 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>[] = []
 
-    if (debounceMs > 0) {
-      await new Promise((r) => setTimeout(r, debounceMs))
-    }
+    for (const validateObj of validates) {
+      if (!validateObj.validate) continue
+      const key = getErrorMapKey(validateObj.cause)
+      const fieldValidatorMeta = this.getInfo().validationMetaMap[key]
 
-    const doValidate = () => {
-      if (this.options.validator && typeof validate !== 'function') {
-        return (this.options.validator as Validator<TData>)().validateAsync(
-          value,
-          validate,
-        )
-      }
+      fieldValidatorMeta?.lastAbortController.abort()
+      const controller = new AbortController()
 
-      if (this.form.options.validator && typeof validate !== 'function') {
-        return (
-          this.form.options.validator as Validator<TData>
-        )().validateAsync(value, validate)
+      this.getInfo().validationMetaMap[key] = {
+        lastAbortController: controller,
       }
 
-      return (validate as ValidateFn<TParentData, TName, ValidatorType, TData>)(
-        value,
-        this as never,
+      promises.push(
+        new Promise<ValidationError | undefined>(async (resolve) => {
+          let rawError!: ValidationError | undefined
+          try {
+            rawError = await new Promise((rawResolve, rawReject) => {
+              setTimeout(async () => {
+                if (controller.signal.aborted) return rawResolve(undefined)
+                try {
+                  rawResolve(
+                    await this.runValidator({
+                      validate: validateObj.validate,
+                      value: {
+                        value,
+                        fieldApi: this,
+                        signal: controller.signal,
+                      },
+                      type: 'validateAsync',
+                    }),
+                  )
+                } catch (e) {
+                  rawReject(e)
+                }
+              }, validateObj.debounceMs)
+            })
+          } catch (e: unknown) {
+            rawError = e as ValidationError
+          }
+          const error = normalizeError(rawError)
+          this.setMeta((prev) => {
+            return {
+              ...prev,
+              errorMap: {
+                // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+                ...prev?.errorMap,
+                [getErrorMapKey(cause)]: error,
+              },
+            }
+          })
+
+          resolve(error)
+        }),
       )
     }
 
-    // Only kick off validation if this validation is the latest attempt
-    if (checkLatest()) {
-      const prevErrors = this.getMeta().errors
-      try {
-        const rawError = await doValidate()
-        if (checkLatest()) {
-          const error = normalizeError(rawError)
-          this.setMeta((prev) => ({
-            ...prev,
-            isValidating: false,
-            errorMap: {
-              ...prev.errorMap,
-              [getErrorMapKey(cause)]: error,
-            },
-          }))
-          this.getInfo().validationResolve?.([...prevErrors, error])
-        }
-      } catch (error) {
-        if (checkLatest()) {
-          this.getInfo().validationReject?.([...prevErrors, error])
-          throw error
-        }
-      } finally {
-        if (checkLatest()) {
-          this.setMeta((prev) => ({ ...prev, isValidating: false }))
-          delete this.getInfo().validationPromise
-        }
-      }
+    let results: ValidationError[] = []
+    if (promises.length) {
+      results = await Promise.all(promises)
     }
 
-    // Always return the latest validation promise to the caller
-    return (await this.getInfo().validationPromise) ?? []
+    this.setMeta((prev) => ({ ...prev, isValidating: false }))
+
+    return results.filter(Boolean)
   }
 
   validate = (
@@ -559,10 +650,8 @@ export class FieldApi<
     // Attempt to sync validate first
     const { hasErrored } = this.validateSync(value, cause)
 
-    if (hasErrored) {
-      if (!this.options.asyncAlways) {
-        return this.state.meta.errors
-      }
+    if (hasErrored && !this.options.asyncAlways) {
+      return this.state.meta.errors
     }
     // No error? Attempt async validation
     return this.validateAsync(value, cause)
@@ -598,11 +687,14 @@ function getErrorMapKey(cause: ValidationCause) {
   switch (cause) {
     case 'submit':
       return 'onSubmit'
-    case 'change':
-      return 'onChange'
     case 'blur':
       return 'onBlur'
     case 'mount':
       return 'onMount'
+    case 'server':
+      return 'onServer'
+    case 'change':
+    default:
+      return 'onChange'
   }
 }