@tanstack/form-core 0.40.4 → 0.41.0

package/src/FormApi.ts

@@ -1,4 +1,4 @@
-import { Store } from '@tanstack/store'
+import { Derived, Store, batch } from '@tanstack/store'
 import {
   deleteBy,
   functionalUpdate,
@@ -13,7 +13,7 @@ import {
   standardSchemaValidator,
 } from './standardSchemaValidator'
 import type { StandardSchemaV1 } from './standardSchemaValidator'
-import type { FieldApi, FieldMeta } from './FieldApi'
+import type { FieldApi, FieldMeta, FieldMetaBase } from './FieldApi'
 import type {
   FormValidationError,
   FormValidationErrorMap,
@@ -225,23 +225,11 @@ export type FieldInfo<
 /**
  * An object representing the current state of the form.
  */
-export type FormState<TFormData> = {
+export type BaseFormState<TFormData> = {
   /**
    * The current values of the form fields.
    */
   values: TFormData
-  /**
-   * A boolean indicating if the form is currently validating.
-   */
-  isFormValidating: boolean
-  /**
-   * A boolean indicating if the form is valid.
-   */
-  isFormValid: boolean
-  /**
-   * The error array for the form itself.
-   */
-  errors: ValidationError[]
   /**
    * The error map for the form itself.
    */
@@ -251,17 +239,9 @@ export type FormState<TFormData> = {
    */
   validationMetaMap: Record<ValidationErrorMapKeys, ValidationMeta | undefined>
   /**
-   * A record of field metadata for each field in the form.
-   */
-  fieldMeta: Record<DeepKeys<TFormData>, FieldMeta>
-  /**
-   * A boolean indicating if any of the form fields are currently validating.
-   */
-  isFieldsValidating: boolean
-  /**
-   * A boolean indicating if all the form fields are valid.
+   * A record of field metadata for each field in the form, not including the derived properties, like `errors` and such
    */
-  isFieldsValid: boolean
+  fieldMetaBase: Record<DeepKeys<TFormData>, FieldMetaBase>
   /**
    * A boolean indicating if the form is currently in the process of being submitted after `handleSubmit` is called.
    *
@@ -275,6 +255,41 @@ export type FormState<TFormData> = {
    *
    */
   isSubmitting: boolean
+  /**
+   * A boolean indicating if the form has been submitted.
+   */
+  isSubmitted: boolean
+  /**
+   * A boolean indicating if the form or any of its fields are currently validating.
+   */
+  isValidating: boolean
+  /**
+   * A counter for tracking the number of submission attempts.
+   */
+  submissionAttempts: number
+}
+
+export type DerivedFormState<TFormData> = {
+  /**
+   * A boolean indicating if the form is currently validating.
+   */
+  isFormValidating: boolean
+  /**
+   * A boolean indicating if the form is valid.
+   */
+  isFormValid: boolean
+  /**
+   * The error array for the form itself.
+   */
+  errors: ValidationError[]
+  /**
+   * A boolean indicating if any of the form fields are currently validating.
+   */
+  isFieldsValidating: boolean
+  /**
+   * A boolean indicating if all the form fields are valid.
+   */
+  isFieldsValid: boolean
   /**
    * A boolean indicating if any of the form fields have been touched.
    */
@@ -291,14 +306,6 @@ export type FormState<TFormData> = {
    * A boolean indicating if none of the form's fields' values have been modified by the user. `True` if the user have not modified any of the fields. Opposite of `isDirty`.
    */
   isPristine: boolean
-  /**
-   * A boolean indicating if the form has been submitted.
-   */
-  isSubmitted: boolean
-  /**
-   * A boolean indicating if the form or any of its fields are currently validating.
-   */
-  isValidating: boolean
   /**
    * A boolean indicating if the form and all its fields are valid.
    */
@@ -308,31 +315,23 @@ export type FormState<TFormData> = {
    */
   canSubmit: boolean
   /**
-   * A counter for tracking the number of submission attempts.
+   * A record of field metadata for each field in the form.
    */
-  submissionAttempts: number
+  fieldMeta: Record<DeepKeys<TFormData>, FieldMeta>
 }
 
+export type FormState<TFormData> = BaseFormState<TFormData> &
+  DerivedFormState<TFormData>
+
 function getDefaultFormState<TFormData>(
   defaultState: Partial<FormState<TFormData>>,
-): FormState<TFormData> {
+): BaseFormState<TFormData> {
   return {
     values: defaultState.values ?? ({} as never),
-    errors: defaultState.errors ?? [],
     errorMap: defaultState.errorMap ?? {},
-    fieldMeta: defaultState.fieldMeta ?? ({} as never),
-    canSubmit: defaultState.canSubmit ?? true,
-    isFieldsValid: defaultState.isFieldsValid ?? false,
-    isFieldsValidating: defaultState.isFieldsValidating ?? false,
-    isFormValid: defaultState.isFormValid ?? false,
-    isFormValidating: defaultState.isFormValidating ?? false,
+    fieldMetaBase: defaultState.fieldMetaBase ?? ({} as never),
     isSubmitted: defaultState.isSubmitted ?? false,
     isSubmitting: defaultState.isSubmitting ?? false,
-    isTouched: defaultState.isTouched ?? false,
-    isBlurred: defaultState.isBlurred ?? false,
-    isPristine: defaultState.isPristine ?? true,
-    isDirty: defaultState.isDirty ?? false,
-    isValid: defaultState.isValid ?? false,
     isValidating: defaultState.isValidating ?? false,
     submissionAttempts: defaultState.submissionAttempts ?? 0,
     validationMetaMap: defaultState.validationMetaMap ?? {
@@ -366,24 +365,19 @@ export class FormApi<
    * The options for the form.
    */
   options: FormOptions<TFormData, TFormValidator> = {}
-  /**
-   * A [TanStack Store instance](https://tanstack.com/store/latest/docs/reference/Store) that keeps track of the form's state.
-   */
-  store!: Store<FormState<TFormData>>
-  /**
-   * The current state of the form.
-   *
-   * **Note:**
-   * Do not use `state` directly, as it is not reactive.
-   * Please use useStore(form.store) utility to subscribe to state
-   */
-  state!: FormState<TFormData>
+  baseStore!: Store<BaseFormState<TFormData>>
+  fieldMetaDerived!: Derived<Record<DeepKeys<TFormData>, FieldMeta>>
+  store!: Derived<FormState<TFormData>>
   /**
    * A record of field information for each field in the form.
    */
   fieldInfo: Record<DeepKeys<TFormData>, FieldInfo<TFormData, TFormValidator>> =
     {} as any
 
+  get state() {
+    return this.store.state
+  }
+
   /**
    * @private
    */
@@ -393,103 +387,172 @@ export class FormApi<
    * Constructs a new `FormApi` instance with the given form options.
    */
   constructor(opts?: FormOptions<TFormData, TFormValidator>) {
-    this.store = new Store<FormState<TFormData>>(
+    this.baseStore = new Store(
       getDefaultFormState({
         ...(opts?.defaultState as any),
         values: opts?.defaultValues ?? opts?.defaultState?.values,
         isFormValid: true,
       }),
-      {
-        onUpdate: () => {
-          let { state } = this.store
-          // Computed state
-          const fieldMetaValues = Object.values(state.fieldMeta) as (
-            | FieldMeta
-            | undefined
-          )[]
+    )
 
-          const isFieldsValidating = fieldMetaValues.some(
-            (field) => field?.isValidating,
-          )
+    this.fieldMetaDerived = new Derived({
+      deps: [this.baseStore],
+      fn: ({ prevDepVals, currDepVals, prevVal: _prevVal }) => {
+        const prevVal = _prevVal as
+          | Record<DeepKeys<TFormData>, FieldMeta>
+          | undefined
+        const prevBaseStore = prevDepVals?.[0]
+        const currBaseStore = currDepVals[0]
+
+        const fieldMeta = {} as FormState<TFormData>['fieldMeta']
+        for (const fieldName of Object.keys(
+          currBaseStore.fieldMetaBase,
+        ) as Array<keyof typeof currBaseStore.fieldMetaBase>) {
+          const currBaseVal = currBaseStore.fieldMetaBase[
+            fieldName as never
+          ] as FieldMetaBase
+
+          const prevBaseVal = prevBaseStore?.fieldMetaBase[
+            fieldName as never
+          ] as FieldMetaBase | undefined
+
+          let fieldErrors =
+            prevVal?.[fieldName as never as keyof typeof prevVal]?.errors
+          if (!prevBaseVal || currBaseVal.errorMap !== prevBaseVal.errorMap) {
+            // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+            fieldErrors = Object.values(currBaseVal.errorMap ?? {}).filter(
+              (val: unknown) => val !== undefined,
+            )
+          }
 
-          const isFieldsValid = !fieldMetaValues.some(
-            (field) =>
-              field?.errorMap &&
-              isNonEmptyArray(Object.values(field.errorMap).filter(Boolean)),
-          )
+          // As a primitive, we don't need to aggressively persist the same referencial value for performance reasons
+          const isFieldPristine = !currBaseVal.isDirty
 
-          const isTouched = fieldMetaValues.some((field) => field?.isTouched)
-          const isBlurred = fieldMetaValues.some((field) => field?.isBlurred)
+          fieldMeta[fieldName] = {
+            ...currBaseVal,
+            errors: fieldErrors,
+            isPristine: isFieldPristine,
+          } as FieldMeta
+        }
+
+        return fieldMeta
+      },
+    })
 
+    this.store = new Derived({
+      deps: [this.baseStore, this.fieldMetaDerived],
+      fn: ({ prevDepVals, currDepVals, prevVal: _prevVal }) => {
+        const prevVal = _prevVal as FormState<TFormData> | undefined
+        const prevBaseStore = prevDepVals?.[0]
+        const currBaseStore = currDepVals[0]
+
+        // Computed state
+        const fieldMetaValues = Object.values(currBaseStore.fieldMetaBase) as (
+          | FieldMeta
+          | undefined
+        )[]
+
+        const isFieldsValidating = fieldMetaValues.some(
+          (field) => field?.isValidating,
+        )
+
+        const isFieldsValid = !fieldMetaValues.some(
+          (field) =>
+            field?.errorMap &&
+            isNonEmptyArray(Object.values(field.errorMap).filter(Boolean)),
+        )
+
+        const isTouched = fieldMetaValues.some((field) => field?.isTouched)
+        const isBlurred = fieldMetaValues.some((field) => field?.isBlurred)
+
+        const shouldInvalidateOnMount =
           // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
-          if (isTouched && state?.errorMap?.onMount) {
-            state.errorMap.onMount = undefined
-          }
+          isTouched && currBaseStore?.errorMap?.onMount
 
-          const isDirty = fieldMetaValues.some((field) => field?.isDirty)
-          const isPristine = !isDirty
+        const isDirty = fieldMetaValues.some((field) => field?.isDirty)
+        const isPristine = !isDirty
 
-          const hasOnMountError = Boolean(
+        const hasOnMountError = Boolean(
+          // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+          currBaseStore.errorMap?.onMount ||
             // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
-            state.errorMap?.onMount ||
-              // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
-              fieldMetaValues.some((f) => f?.errorMap?.onMount),
-          )
+            fieldMetaValues.some((f) => f?.errorMap?.onMount),
+        )
 
-          const isValidating = isFieldsValidating || state.isFormValidating
-          state.errors = Object.values(state.errorMap).reduce((prev, curr) => {
-            // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
-            if (curr === undefined) return prev
-            if (typeof curr === 'string') {
-              prev.push(curr)
-              return prev
-            } else if (curr && isFormValidationError(curr)) {
-              prev.push(curr.form)
+        const isValidating = !!isFieldsValidating
+
+        // As `errors` is not a primitive, we need to aggressively persist the same referencial value for performance reasons
+        let errors = prevVal?.errors ?? []
+        if (
+          !prevBaseStore ||
+          currBaseStore.errorMap !== prevBaseStore.errorMap
+        ) {
+          errors = Object.values(currBaseStore.errorMap).reduce(
+            (prev, curr) => {
+              // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+              if (curr === undefined) return prev
+              if (typeof curr === 'string') {
+                prev.push(curr)
+                return prev
+              } else if (curr && isFormValidationError(curr)) {
+                prev.push(curr.form)
+                return prev
+              }
               return prev
-            }
-            return prev
-          }, [] as ValidationError[])
-          const isFormValid = state.errors.length === 0
-          const isValid = isFieldsValid && isFormValid
-          const canSubmit =
-            (state.submissionAttempts === 0 &&
-              !isTouched &&
-              !hasOnMountError) ||
-            (!isValidating && !state.isSubmitting && isValid)
-
-          state = {
-            ...state,
-            isFieldsValidating,
-            isFieldsValid,
-            isFormValid,
-            isValid,
-            canSubmit,
-            isTouched,
-            isBlurred,
-            isPristine,
-            isDirty,
-          }
+            },
+            [] as ValidationError[],
+          )
+        }
 
-          this.state = state
-          this.store.state = this.state
+        const isFormValid = errors.length === 0
+        const isValid = isFieldsValid && isFormValid
+        const canSubmit =
+          (currBaseStore.submissionAttempts === 0 &&
+            !isTouched &&
+            !hasOnMountError) ||
+          (!isValidating && !currBaseStore.isSubmitting && isValid)
+
+        let errorMap = currBaseStore.errorMap
+        if (shouldInvalidateOnMount) {
+          errors = errors.filter(
+            (err) => err !== currBaseStore.errorMap.onMount,
+          )
+          errorMap = Object.assign(errorMap, { onMount: undefined })
+        }
 
-          // 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])
+        let state = {
+          ...currBaseStore,
+          errorMap,
+          fieldMeta: this.fieldMetaDerived.state,
+          errors,
+          isFieldsValidating,
+          isFieldsValid,
+          isFormValid,
+          isValid,
+          canSubmit,
+          isTouched,
+          isBlurred,
+          isPristine,
+          isDirty,
+        } as FormState<TFormData>
+
+        // 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) {
+          const newObj = Object.assign({}, this, { state })
+          // This mutates the state
+          this.options.transform?.fn(newObj)
+          state = newObj.state
+          this.prevTransformArray = transformArray
+        }
 
-          if (shouldTransform) {
-            // This mutates the state
-            this.options.transform?.fn(this)
-            this.store.state = this.state
-            this.prevTransformArray = transformArray
-          }
-        },
+        return state
       },
-    )
-
-    this.state = this.store.state
+    })
 
     this.update(opts || {})
   }
@@ -530,10 +593,17 @@ export class FormApi<
   }
 
   mount = () => {
+    const cleanupFieldMetaDerived = this.fieldMetaDerived.mount()
+    const cleanupStoreDerived = this.store.mount()
+    const cleanup = () => {
+      cleanupFieldMetaDerived()
+      cleanupStoreDerived()
+    }
     const { onMount } = this.options.validators || {}
-    if (!onMount) return
-
+    if (!onMount) return cleanup
     this.validateSync('mount')
+
+    return cleanup
   }
 
   /**
@@ -547,7 +617,7 @@ export class FormApi<
     // 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(() => {
+    batch(() => {
       const shouldUpdateValues =
         options.defaultValues &&
         options.defaultValues !== oldOptions.defaultValues &&
@@ -557,7 +627,7 @@ export class FormApi<
         options.defaultState !== oldOptions.defaultState &&
         !this.state.isTouched
 
-      this.store.setState(() =>
+      this.baseStore.setState(() =>
         getDefaultFormState(
           Object.assign(
             {},
@@ -585,7 +655,7 @@ export class FormApi<
    */
   reset = (values?: TFormData, opts?: { keepDefaultValues?: boolean }) => {
     const { fieldMeta: currentFieldMeta } = this.state
-    const fieldMeta = this.resetFieldMeta(currentFieldMeta)
+    const fieldMetaBase = this.resetFieldMeta(currentFieldMeta)
 
     if (values && !opts?.keepDefaultValues) {
       this.options = {
@@ -594,14 +664,14 @@ export class FormApi<
       }
     }
 
-    this.store.setState(() =>
+    this.baseStore.setState(() =>
       getDefaultFormState({
         ...(this.options.defaultState as any),
         values:
           values ??
           this.options.defaultValues ??
           this.options.defaultState?.values,
-        fieldMeta,
+        fieldMetaBase,
       }),
     )
   }
@@ -611,7 +681,7 @@ export class FormApi<
    */
   validateAllFields = async (cause: ValidationCause) => {
     const fieldValidationPromises: Promise<ValidationError[]>[] = [] as any
-    this.store.batch(() => {
+    batch(() => {
       void (
         Object.values(this.fieldInfo) as FieldInfo<any, TFormValidator>[]
       ).forEach((field) => {
@@ -661,7 +731,7 @@ export class FormApi<
 
     // Validate the fields
     const fieldValidationPromises: Promise<ValidationError[]>[] = [] as any
-    this.store.batch(() => {
+    batch(() => {
       fieldsToValidate.forEach((nestedField) => {
         fieldValidationPromises.push(
           Promise.resolve().then(() => this.validateField(nestedField, cause)),
@@ -708,7 +778,7 @@ export class FormApi<
 
     const fieldsErrorMap: FieldsErrorMapFromValidator<TFormData> = {}
 
-    this.store.batch(() => {
+    batch(() => {
       for (const validateObj of validates) {
         if (!validateObj.validate) continue
 
@@ -750,7 +820,7 @@ export class FormApi<
         }
 
         if (this.state.errorMap[errorMapKey] !== formError) {
-          this.store.setState((prev) => ({
+          this.baseStore.setState((prev) => ({
             ...prev,
             errorMap: {
               ...prev.errorMap,
@@ -775,7 +845,7 @@ export class FormApi<
       cause !== 'submit' &&
       !hasErrored
     ) {
-      this.store.setState((prev) => ({
+      this.baseStore.setState((prev) => ({
         ...prev,
         errorMap: {
           ...prev.errorMap,
@@ -796,7 +866,7 @@ export class FormApi<
     const validates = getAsyncValidatorArray(cause, this.options)
 
     if (!this.state.isFormValidating) {
-      this.store.setState((prev) => ({ ...prev, isFormValidating: true }))
+      this.baseStore.setState((prev) => ({ ...prev, isFormValidating: true }))
     }
 
     /**
@@ -876,7 +946,7 @@ export class FormApi<
               }
             }
           }
-          this.store.setState((prev) => ({
+          this.baseStore.setState((prev) => ({
             ...prev,
             errorMap: {
               ...prev.errorMap,
@@ -913,7 +983,7 @@ export class FormApi<
       }
     }
 
-    this.store.setState((prev) => ({
+    this.baseStore.setState((prev) => ({
       ...prev,
       isFormValidating: false,
     }))
@@ -944,7 +1014,7 @@ export class FormApi<
    * Handles the form submission, performs validation, and calls the appropriate onSubmit or onInvalidSubmit callbacks.
    */
   handleSubmit = async () => {
-    this.store.setState((old) => ({
+    this.baseStore.setState((old) => ({
       ...old,
       // Submission attempts mark the form as not submitted
       isSubmitted: false,
@@ -955,10 +1025,10 @@ export class FormApi<
     // Don't let invalid forms submit
     if (!this.state.canSubmit) return
 
-    this.store.setState((d) => ({ ...d, isSubmitting: true }))
+    this.baseStore.setState((d) => ({ ...d, isSubmitting: true }))
 
     const done = () => {
-      this.store.setState((prev) => ({ ...prev, isSubmitting: false }))
+      this.baseStore.setState((prev) => ({ ...prev, isSubmitting: false }))
     }
 
     // Validate form and all fields
@@ -974,7 +1044,7 @@ export class FormApi<
       return
     }
 
-    this.store.batch(() => {
+    batch(() => {
       void (
         Object.values(this.fieldInfo) as FieldInfo<TFormData, TFormValidator>[]
       ).forEach((field) => {
@@ -989,8 +1059,8 @@ export class FormApi<
       // Run the submit code
       await this.options.onSubmit?.({ value: this.state.values, formApi: this })
 
-      this.store.batch(() => {
-        this.store.setState((prev) => ({ ...prev, isSubmitted: true }))
+      batch(() => {
+        this.baseStore.setState((prev) => ({ ...prev, isSubmitted: true }))
         done()
       })
     } catch (err) {
@@ -1041,12 +1111,15 @@ export class FormApi<
     field: TField,
     updater: Updater<FieldMeta>,
   ) => {
-    this.store.setState((prev) => {
+    this.baseStore.setState((prev) => {
       return {
         ...prev,
-        fieldMeta: {
-          ...prev.fieldMeta,
-          [field]: functionalUpdate(updater, prev.fieldMeta[field]),
+        fieldMetaBase: {
+          ...prev.fieldMetaBase,
+          [field]: functionalUpdate(
+            updater,
+            prev.fieldMetaBase[field] as never,
+          ),
         },
       }
     })
@@ -1083,7 +1156,7 @@ export class FormApi<
   ) => {
     const dontUpdateMeta = opts?.dontUpdateMeta ?? false
 
-    this.store.batch(() => {
+    batch(() => {
       if (!dontUpdateMeta) {
         this.setFieldMeta(field, (prev) => ({
           ...prev,
@@ -1097,7 +1170,7 @@ export class FormApi<
         }))
       }
 
-      this.store.setState((prev) => {
+      this.baseStore.setState((prev) => {
         return {
           ...prev,
           values: setBy(prev.values, field, updater),
@@ -1107,10 +1180,10 @@ export class FormApi<
   }
 
   deleteField = <TField extends DeepKeys<TFormData>>(field: TField) => {
-    this.store.setState((prev) => {
+    this.baseStore.setState((prev) => {
       const newState = { ...prev }
       newState.values = deleteBy(newState.values, field)
-      delete newState.fieldMeta[field]
+      delete newState.fieldMetaBase[field]
 
       return newState
     })
@@ -1281,7 +1354,7 @@ export class FormApi<
    * Updates the form's errorMap
    */
   setErrorMap(errorMap: ValidationErrorMap) {
-    this.store.setState((prev) => ({
+    this.baseStore.setState((prev) => ({
       ...prev,
       errorMap: {
         ...prev.errorMap,