@tanstack/form-core 0.10.3 → 0.12.0

package/src/FormApi.ts

@@ -1,80 +1,131 @@
 import { Store } from '@tanstack/store'
 import type { DeepKeys, DeepValue, Updater } from './utils'
 import {
+  getAsyncValidatorArray,
+  getSyncValidatorArray,
   deleteBy,
   functionalUpdate,
   getBy,
   isNonEmptyArray,
   setBy,
 } from './utils'
-import type { FieldApi, FieldMeta, ValidationCause } from './FieldApi'
-import type { ValidationError, Validator } from './types'
-
-type ValidateFn<TData, ValidatorType> = (
-  values: TData,
-  formApi: FormApi<TData, ValidatorType>,
-) => ValidationError
-
-type ValidateOrFn<TData, ValidatorType> = ValidatorType extends Validator<TData>
-  ? Parameters<ReturnType<ValidatorType>['validate']>[1]
-  : ValidateFn<TData, ValidatorType>
-
-type ValidateAsyncFn<TData, ValidatorType> = (
-  value: TData,
-  fieldApi: FormApi<TData, ValidatorType>,
-) => ValidationError | Promise<ValidationError>
-
-export type FormOptions<TData, ValidatorType> = {
-  defaultValues?: TData
-  defaultState?: Partial<FormState<TData>>
-  asyncAlways?: boolean
-  asyncDebounceMs?: number
-  validator?: ValidatorType
-  onMount?: ValidateOrFn<TData, ValidatorType>
-  onChange?: ValidateOrFn<TData, ValidatorType>
-  onChangeAsync?: ValidateAsyncFn<TData, ValidatorType>
+import type { FieldApi, FieldMeta } from './FieldApi'
+import type {
+  ValidationError,
+  ValidationErrorMap,
+  Validator,
+  ValidationCause,
+  ValidationErrorMapKeys,
+} from './types'
+
+export type FormValidateFn<
+  TFormData,
+  TFormValidator extends Validator<TFormData, unknown> | undefined = undefined,
+> = (props: {
+  value: TFormData
+  formApi: FormApi<TFormData, TFormValidator>
+}) => ValidationError
+
+export type FormValidateOrFn<
+  TFormData,
+  TFormValidator extends Validator<TFormData, unknown> | undefined = undefined,
+> = TFormValidator extends Validator<TFormData, infer TFN>
+  ? TFN
+  : FormValidateFn<TFormData, TFormValidator>
+
+export type FormValidateAsyncFn<
+  TFormData,
+  TFormValidator extends Validator<TFormData, unknown> | undefined = undefined,
+> = (props: {
+  value: TFormData
+  formApi: FormApi<TFormData, TFormValidator>
+  signal: AbortSignal
+}) => ValidationError | Promise<ValidationError>
+
+export type FormAsyncValidateOrFn<
+  TFormData,
+  TFormValidator extends Validator<TFormData, unknown> | undefined = undefined,
+> = TFormValidator extends Validator<TFormData, infer FFN>
+  ? FFN | FormValidateAsyncFn<TFormData, TFormValidator>
+  : FormValidateAsyncFn<TFormData, TFormValidator>
+
+export interface FormValidators<
+  TFormData,
+  TFormValidator extends Validator<TFormData, unknown> | undefined = undefined,
+> {
+  onMount?: FormValidateOrFn<TFormData, TFormValidator>
+  onChange?: FormValidateOrFn<TFormData, TFormValidator>
+  onChangeAsync?: FormAsyncValidateOrFn<TFormData, TFormValidator>
   onChangeAsyncDebounceMs?: number
-  onBlur?: ValidateOrFn<TData, ValidatorType>
-  onBlurAsync?: ValidateAsyncFn<TData, ValidatorType>
+  onBlur?: FormValidateOrFn<TFormData, TFormValidator>
+  onBlurAsync?: FormAsyncValidateOrFn<TFormData, TFormValidator>
   onBlurAsyncDebounceMs?: number
-  onSubmit?: (
-    values: TData,
-    formApi: FormApi<TData, ValidatorType>,
-  ) => any | Promise<any>
-  onSubmitInvalid?: (
-    values: TData,
-    formApi: FormApi<TData, ValidatorType>,
-  ) => void
+  onSubmit?: FormValidateOrFn<TFormData, TFormValidator>
+  onSubmitAsync?: FormAsyncValidateOrFn<TFormData, TFormValidator>
+  onSubmitAsyncDebounceMs?: number
 }
 
-export type FieldInfo<TFormData, ValidatorType> = {
-  instances: Record<string, FieldApi<TFormData, any, unknown, ValidatorType>>
-} & ValidationMeta
+export interface FormTransform<
+  TFormData,
+  TFormValidator extends Validator<TFormData, unknown> | undefined = undefined,
+> {
+  fn: (
+    formBase: FormApi<TFormData, TFormValidator>,
+  ) => FormApi<TFormData, TFormValidator>
+  deps: unknown[]
+}
 
-export type ValidationMeta = {
-  validationCount?: number
-  validationAsyncCount?: number
-  validationPromise?: Promise<ValidationError[] | undefined>
-  validationResolve?: (errors: ValidationError[] | undefined) => void
-  validationReject?: (errors: unknown) => void
+export interface FormOptions<
+  TFormData,
+  TFormValidator extends Validator<TFormData, unknown> | undefined = undefined,
+> {
+  defaultValues?: TFormData
+  defaultState?: Partial<FormState<TFormData>>
+  asyncAlways?: boolean
+  asyncDebounceMs?: number
+  validatorAdapter?: TFormValidator
+  validators?: FormValidators<TFormData, TFormValidator>
+  onSubmit?: (props: {
+    value: TFormData
+    formApi: FormApi<TFormData, TFormValidator>
+  }) => any | Promise<any>
+  onSubmitInvalid?: (props: {
+    value: TFormData
+    formApi: FormApi<TFormData, TFormValidator>
+  }) => void
+  transform?: FormTransform<TFormData, TFormValidator>
 }
 
-export type ValidationErrorMapKeys = `on${Capitalize<ValidationCause>}`
+export type ValidationMeta = {
+  lastAbortController: AbortController
+}
 
-export type ValidationErrorMap = {
-  [K in ValidationErrorMapKeys]?: ValidationError
+export type FieldInfo<
+  TFormData,
+  TFormValidator extends Validator<TFormData, unknown> | undefined = undefined,
+> = {
+  instances: Record<
+    string,
+    FieldApi<
+      TFormData,
+      any,
+      Validator<unknown, unknown> | undefined,
+      TFormValidator
+    >
+  >
+  validationMetaMap: Record<ValidationErrorMapKeys, ValidationMeta | undefined>
 }
 
-export type FormState<TData> = {
-  values: TData
+export type FormState<TFormData> = {
+  values: TFormData
   // Form Validation
   isFormValidating: boolean
-  formValidationCount: number
   isFormValid: boolean
   errors: ValidationError[]
   errorMap: ValidationErrorMap
+  validationMetaMap: Record<ValidationErrorMapKeys, ValidationMeta | undefined>
   // Fields
-  fieldMeta: Record<DeepKeys<TData>, FieldMeta>
+  fieldMeta: Record<DeepKeys<TFormData>, FieldMeta>
   isFieldsValidating: boolean
   isFieldsValid: boolean
   isSubmitting: boolean
@@ -87,9 +138,9 @@ export type FormState<TData> = {
   submissionAttempts: number
 }
 
-function getDefaultFormState<TData>(
-  defaultState: Partial<FormState<TData>>,
-): FormState<TData> {
+function getDefaultFormState<TFormData>(
+  defaultState: Partial<FormState<TFormData>>,
+): FormState<TFormData> {
   return {
     values: defaultState.values ?? ({} as never),
     errors: defaultState.errors ?? [],
@@ -106,23 +157,32 @@ function getDefaultFormState<TData>(
     isValid: defaultState.isValid ?? false,
     isValidating: defaultState.isValidating ?? false,
     submissionAttempts: defaultState.submissionAttempts ?? 0,
-    formValidationCount: defaultState.formValidationCount ?? 0,
+    validationMetaMap: defaultState.validationMetaMap ?? {
+      onChange: undefined,
+      onBlur: undefined,
+      onSubmit: undefined,
+      onMount: undefined,
+      onServer: undefined,
+    },
   }
 }
 
-export class FormApi<TFormData, ValidatorType> {
-  // // This carries the context for nested fields
-  options: FormOptions<TFormData, ValidatorType> = {}
+export class FormApi<
+  TFormData,
+  TFormValidator extends Validator<TFormData, unknown> | undefined = undefined,
+> {
+  options: FormOptions<TFormData, TFormValidator> = {}
   store!: Store<FormState<TFormData>>
   // Do not use __state directly, as it is not reactive.
   // Please use form.useStore() utility to subscribe to state
   state!: FormState<TFormData>
-  fieldInfo: Record<DeepKeys<TFormData>, FieldInfo<TFormData, ValidatorType>> =
+  // // This carries the context for nested fields
+  fieldInfo: Record<DeepKeys<TFormData>, FieldInfo<TFormData, TFormValidator>> =
     {} as any
-  fieldName?: string
-  validationMeta: ValidationMeta = {}
 
-  constructor(opts?: FormOptions<TFormData, ValidatorType>) {
+  prevTransformArray: unknown[] = []
+
+  constructor(opts?: FormOptions<TFormData, TFormValidator>) {
     this.store = new Store<FormState<TFormData>>(
       getDefaultFormState({
         ...(opts?.defaultState as any),
@@ -170,8 +230,21 @@ export class FormApi<TFormData, ValidatorType> {
             isTouched,
           }
 
-          this.store.state = state
           this.state = state
+          this.store.state = this.state
+
+          // Only run transform if state has shallowly changed - IE how React.useEffect works
+          const transformArray = this.options.transform?.deps ?? []
+          const shouldTransform =
+            transformArray.length !== this.prevTransformArray.length ||
+            transformArray.some((val, i) => val !== this.prevTransformArray[i])
+
+          if (shouldTransform) {
+            // This mutates the state
+            this.options.transform?.fn(this)
+            this.store.state = this.state
+            this.prevTransformArray = transformArray
+          }
         },
       },
     )
@@ -181,24 +254,35 @@ export class FormApi<TFormData, ValidatorType> {
     this.update(opts || {})
   }
 
-  mount = () => {
-    const doValidate = () => {
-      if (
-        this.options.validator &&
-        typeof this.options.onMount !== 'function'
-      ) {
-        return (this.options.validator as Validator<TFormData>)().validate(
-          this.state.values,
-          this.options.onMount,
-        )
-      }
-      return (this.options.onMount as ValidateFn<TFormData, ValidatorType>)(
-        this.state.values,
-        this,
-      )
+  runValidator<
+    TValue extends { value: TFormData; formApi: FormApi<any, any> },
+    TType extends 'validate' | 'validateAsync',
+  >(props: {
+    validate: TType extends 'validate'
+      ? FormValidateOrFn<TFormData, TFormValidator>
+      : FormAsyncValidateOrFn<TFormData, TFormValidator>
+    value: TValue
+    type: TType
+  }): ReturnType<ReturnType<Validator<any>>[TType]> {
+    const adapter = this.options.validatorAdapter
+    if (adapter && typeof props.validate !== 'function') {
+      return adapter()[props.type](props.value, props.validate) as never
     }
-    if (!this.options.onMount) return
-    const error = doValidate()
+
+    return (props.validate as FormValidateFn<any, any>)(props.value) as never
+  }
+
+  mount = () => {
+    const { onMount } = this.options.validators || {}
+    if (!onMount) return
+    const error = this.runValidator({
+      validate: onMount,
+      value: {
+        value: this.state.values,
+        formApi: this,
+      },
+      type: 'validate',
+    })
     if (error) {
       this.store.setState((prev) => ({
         ...prev,
@@ -207,17 +291,22 @@ export class FormApi<TFormData, ValidatorType> {
     }
   }
 
-  update = (options?: FormOptions<TFormData, ValidatorType>) => {
+  update = (options?: FormOptions<TFormData, TFormValidator>) => {
     if (!options) return
 
+    const oldOptions = this.options
+
+    // Options need to be updated first so that when the store is updated, the state is correct for the derived state
+    this.options = options
+
     this.store.batch(() => {
       const shouldUpdateValues =
         options.defaultValues &&
-        options.defaultValues !== this.options.defaultValues &&
+        options.defaultValues !== oldOptions.defaultValues &&
         !this.state.isTouched
 
       const shouldUpdateState =
-        options.defaultState !== this.options.defaultState &&
+        options.defaultState !== oldOptions.defaultState &&
         !this.state.isTouched
 
       this.store.setState(() =>
@@ -237,8 +326,6 @@ export class FormApi<TFormData, ValidatorType> {
         ),
       )
     })
-
-    this.options = options
   }
 
   reset = () =>
@@ -253,7 +340,7 @@ export class FormApi<TFormData, ValidatorType> {
     const fieldValidationPromises: Promise<ValidationError[]>[] = [] as any
     this.store.batch(() => {
       void (
-        Object.values(this.fieldInfo) as FieldInfo<any, ValidatorType>[]
+        Object.values(this.fieldInfo) as FieldInfo<any, TFormValidator>[]
       ).forEach((field) => {
         Object.values(field.instances).forEach((instance) => {
           // Validate the field
@@ -269,174 +356,157 @@ export class FormApi<TFormData, ValidatorType> {
       })
     })
 
-    return Promise.all(fieldValidationPromises)
+    const fieldErrorMapMap = await Promise.all(fieldValidationPromises)
+    return fieldErrorMapMap.flat()
   }
 
-  validateSync = (cause: ValidationCause): void => {
-    const { onChange, onBlur } = this.options
-    const validate =
-      cause === 'change' ? onChange : cause === 'blur' ? onBlur : undefined
-    if (!validate) return
-
-    const errorMapKey = getErrorMapKey(cause)
-    const doValidate = () => {
-      if (this.options.validator && typeof validate !== 'function') {
-        return (this.options.validator as Validator<TFormData>)().validate(
-          this.state.values,
-          validate,
+  // TODO: This code is copied from FieldApi, we should refactor to share
+  validateSync = (cause: ValidationCause) => {
+    const validates = getSyncValidatorArray(cause, this.options)
+    let hasErrored = false as boolean
+
+    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 errorMapKey = getErrorMapKey(validateObj.cause)
+        if (this.state.errorMap[errorMapKey] !== error) {
+          this.store.setState((prev) => ({
+            ...prev,
+            errorMap: {
+              ...prev.errorMap,
+              [errorMapKey]: error,
+            },
+          }))
+        }
+        if (error) {
+          hasErrored = true
+        }
       }
+    })
 
-      return (validate as ValidateFn<TFormData, ValidatorType>)(
-        this.state.values,
-        this,
-      )
-    }
-
-    const error = normalizeError(doValidate())
-    if (this.state.errorMap[errorMapKey] !== error) {
+    /**
+     *  when we have an error for onSubmit in the state, we want
+     *  to clear the error as soon as the user enters a valid value in the field
+     */
+    const submitErrKey = getErrorMapKey('submit')
+    if (
+      this.state.errorMap[submitErrKey] &&
+      cause !== 'submit' &&
+      !hasErrored
+    ) {
       this.store.setState((prev) => ({
         ...prev,
         errorMap: {
           ...prev.errorMap,
-          [errorMapKey]: error,
+          [submitErrKey]: undefined,
         },
       }))
     }
 
-    if (this.state.errorMap[errorMapKey]) {
-      this.cancelValidateAsync()
-    }
-  }
-
-  __leaseValidateAsync = () => {
-    const count = (this.validationMeta.validationAsyncCount || 0) + 1
-    this.validationMeta.validationAsyncCount = count
-    return count
-  }
-
-  cancelValidateAsync = () => {
-    // Lease a new validation count to ignore any pending validations
-    this.__leaseValidateAsync()
-    // Cancel any pending validation state
-    this.store.setState((prev) => ({
-      ...prev,
-      isFormValidating: false,
-    }))
+    return { hasErrored }
   }
 
   validateAsync = async (
     cause: ValidationCause,
   ): Promise<ValidationError[]> => {
-    const {
-      onChangeAsync,
-      onBlurAsync,
-      asyncDebounceMs,
-      onBlurAsyncDebounceMs,
-      onChangeAsyncDebounceMs,
-    } = this.options
-
-    const validate =
-      cause === 'change'
-        ? onChangeAsync
-        : cause === 'blur'
-        ? onBlurAsync
-        : undefined
-
-    if (!validate) return []
-    const debounceMs =
-      (cause === 'change' ? onChangeAsyncDebounceMs : onBlurAsyncDebounceMs) ??
-      asyncDebounceMs ??
-      0
+    const validates = getAsyncValidatorArray(cause, this.options)
 
     if (!this.state.isFormValidating) {
       this.store.setState((prev) => ({ ...prev, isFormValidating: true }))
     }
 
-    // Use the validationCount for all field instances to
-    // track freshness of the validation
-    const validationAsyncCount = this.__leaseValidateAsync()
-
-    const checkLatest = () =>
-      validationAsyncCount === this.validationMeta.validationAsyncCount
+    /**
+     * 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 (!this.validationMeta.validationPromise) {
-      this.validationMeta.validationPromise = new Promise((resolve, reject) => {
-        this.validationMeta.validationResolve = resolve
-        this.validationMeta.validationReject = reject
-      })
-    }
+    for (const validateObj of validates) {
+      if (!validateObj.validate) continue
+      const key = getErrorMapKey(validateObj.cause)
+      const fieldValidatorMeta = this.state.validationMetaMap[key]
 
-    if (debounceMs > 0) {
-      await new Promise((r) => setTimeout(r, debounceMs))
-    }
+      fieldValidatorMeta?.lastAbortController.abort()
+      const controller = new AbortController()
 
-    const doValidate = () => {
-      if (typeof validate === 'function') {
-        return validate(this.state.values, this) as ValidationError
-      }
-      if (this.options.validator && typeof validate !== 'function') {
-        return (this.options.validator as Validator<TFormData>)().validateAsync(
-          this.state.values,
-          validate,
-        )
+      this.state.validationMetaMap[key] = {
+        lastAbortController: controller,
       }
-      const errorMapKey = getErrorMapKey(cause)
-      throw new Error(
-        `Form validation for ${errorMapKey}Async failed. ${errorMapKey}Async should either be a function, or \`validator\` should be correct.`,
-      )
-    }
 
-    // Only kick off validation if this validation is the latest attempt
-    if (checkLatest()) {
-      const prevErrors = this.state.errors
-      try {
-        const rawError = await doValidate()
-        if (checkLatest()) {
+      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: this.state.values,
+                        formApi: this,
+                        signal: controller.signal,
+                      },
+                      type: 'validateAsync',
+                    }),
+                  )
+                } catch (e) {
+                  rawReject(e)
+                }
+              }, validateObj.debounceMs)
+            })
+          } catch (e: unknown) {
+            rawError = e as ValidationError
+          }
           const error = normalizeError(rawError)
           this.store.setState((prev) => ({
             ...prev,
-            isFormValidating: false,
             errorMap: {
               ...prev.errorMap,
               [getErrorMapKey(cause)]: error,
             },
           }))
-          this.validationMeta.validationResolve?.([...prevErrors, error])
-        }
-      } catch (error) {
-        if (checkLatest()) {
-          this.validationMeta.validationReject?.([...prevErrors, error])
-          throw error
-        }
-      } finally {
-        if (checkLatest()) {
-          this.store.setState((prev) => ({ ...prev, isFormValidating: false }))
-          delete this.validationMeta.validationPromise
-        }
-      }
+
+          resolve(error)
+        }),
+      )
+    }
+
+    let results: ValidationError[] = []
+    if (promises.length) {
+      results = await Promise.all(promises)
     }
-    // Always return the latest validation promise to the caller
-    return (await this.validationMeta.validationPromise) ?? []
+
+    this.store.setState((prev) => ({
+      ...prev,
+      isFormValidating: false,
+    }))
+
+    return results.filter(Boolean)
   }
 
   validate = (
     cause: ValidationCause,
   ): ValidationError[] | Promise<ValidationError[]> => {
-    // Store the previous error for the errorMapKey (eg. onChange, onBlur, onSubmit)
-    const errorMapKey = getErrorMapKey(cause)
-    const prevError = this.state.errorMap[errorMapKey]
-
     // Attempt to sync validate first
-    this.validateSync(cause)
+    const { hasErrored } = this.validateSync(cause)
 
-    const newError = this.state.errorMap[errorMapKey]
-    if (
-      prevError !== newError &&
-      !this.options.asyncAlways &&
-      !(newError === undefined && prevError !== undefined)
-    )
+    if (hasErrored && !this.options.asyncAlways) {
       return this.state.errors
+    }
 
     // No error? Attempt async validation
     return this.validateAsync(cause)
@@ -471,7 +541,10 @@ export class FormApi<TFormData, ValidatorType> {
     // Fields are invalid, do not submit
     if (!this.state.isFieldsValid) {
       done()
-      this.options.onSubmitInvalid?.(this.state.values, this)
+      this.options.onSubmitInvalid?.({
+        value: this.state.values,
+        formApi: this,
+      })
       return
     }
 
@@ -480,13 +553,16 @@ export class FormApi<TFormData, ValidatorType> {
 
     if (!this.state.isValid) {
       done()
-      this.options.onSubmitInvalid?.(this.state.values, this)
+      this.options.onSubmitInvalid?.({
+        value: this.state.values,
+        formApi: this,
+      })
       return
     }
 
     try {
       // Run the submit code
-      await this.options.onSubmit?.(this.state.values, this)
+      await this.options.onSubmit?.({ value: this.state.values, formApi: this })
 
       this.store.batch(() => {
         this.store.setState((prev) => ({ ...prev, isSubmitted: true }))
@@ -510,10 +586,17 @@ export class FormApi<TFormData, ValidatorType> {
 
   getFieldInfo = <TField extends DeepKeys<TFormData>>(
     field: TField,
-  ): FieldInfo<TFormData, ValidatorType> => {
+  ): FieldInfo<TFormData, TFormValidator> => {
     // eslint-disable-next-line  @typescript-eslint/no-unnecessary-condition
     return (this.fieldInfo[field] ||= {
       instances: {},
+      validationMetaMap: {
+        onChange: undefined,
+        onBlur: undefined,
+        onSubmit: undefined,
+        onMount: undefined,
+        onServer: undefined,
+      },
     })
   }
 
@@ -644,11 +727,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'
   }
 }