feat(form-core): Async field onChange with submition handling

examples/react/simple/src/index.tsx

@@ -22,7 +22,7 @@ export default function App() {
     },
     onSubmit: async ({ value }) => {
       // Do something with form data
-      console.log(value)
+      console.log(value, 'Submitted')
     },
   })
 
@@ -76,6 +76,14 @@ export default function App() {
         <div>
           <form.Field
             name="lastName"
+            listeners={{
+              onChangeAsyncDebounceMs: 5_000,
+              onChangeAsync: async ({ value, fieldApi }) => {
+                await new Promise((resolve) => setTimeout(resolve, 1000))
+                if (value === 'CHANGED') return
+                fieldApi.form.setFieldValue('lastName', 'CHANGED')
+              },
+            }}
             children={(field) => (
               <>
                 <label htmlFor={field.name}>Last Name:</label>

packages/form-core/src/FieldApi.ts

@@ -238,11 +238,11 @@
 /**
  * @private
  */
-export type FieldListenerFn<
+type FieldListenerFnProps<
   TParentData,
   TName extends DeepKeys<TParentData>,
   TData extends DeepValue<TParentData, TName> = DeepValue<TParentData, TName>,
-> = (props: {
+> = {
   value: TData
   fieldApi: FieldApi<
     TParentData,
@@ -267,7 +267,25 @@
     any,
     any
   >
-}) => void
+}
+
+/**
+ * @private
+ */
+export type FieldListenerFn<
+  TParentData,
+  TName extends DeepKeys<TParentData>,
+  TData extends DeepValue<TParentData, TName> = DeepValue<TParentData, TName>,
+> = (props: FieldListenerFnProps<TParentData, TName, TData>) => void
+
+/**
+ * @private
+ */
+export type FieldListenerAsyncFn<
+  TParentData,
+  TName extends DeepKeys<TParentData>,
+  TData extends DeepValue<TParentData, TName> = DeepValue<TParentData, TName>,
+> = (props: FieldListenerFnProps<TParentData, TName, TData>) => Promise<void>
 
 export interface FieldValidators<
   TParentData,
@@ -357,6 +375,8 @@
 > {
   onChange?: FieldListenerFn<TParentData, TName, TData>
   onChangeDebounceMs?: number
+  onChangeAsync?: FieldListenerAsyncFn<TParentData, TName, TData>
+  onChangeAsyncDebounceMs?: number
   onBlur?: FieldListenerFn<TParentData, TName, TData>
   onBlurDebounceMs?: number
   onMount?: FieldListenerFn<TParentData, TName, TData>
@@ -983,12 +1003,17 @@
   get state() {
     return this.store.state
   }
+
   timeoutIds: {
     validations: Record<ValidationCause, ReturnType<typeof setTimeout> | null>
     listeners: Record<ListenerCause, ReturnType<typeof setTimeout> | null>
     formListeners: Record<ListenerCause, ReturnType<typeof setTimeout> | null>
   }
 
+  promises: {
+    listeners: Record<ListenerCause, Promise<void> | null>
+  }
+
   /**
    * Initializes a new `FieldApi` instance.
    */
@@ -1023,6 +1048,10 @@
       formListeners: {} as Record<ListenerCause, never>,
     }
 
+    this.promises = {
+      listeners: {} as Record<ListenerCause, Promise<void> | null>,
+    }
+
     this.store = new Derived({
       deps: [this.form.store],
       fn: () => {
@@ -1788,6 +1817,7 @@
       })
     }
 
+    this.triggerOnChangeAsyncListener()
     const fieldDebounceMs = this.options.listeners?.onChangeDebounceMs
     if (fieldDebounceMs && fieldDebounceMs > 0) {
       if (this.timeoutIds.listeners.change) {
@@ -1807,6 +1837,64 @@
       })
     }
   }
+
+  private abortController: AbortController = new AbortController()
+  private collapseController: AbortController = new AbortController()
+  private triggerOnChangeAsyncListener() {
+    const fieldDebounceMs = this.options.listeners?.onChangeAsyncDebounceMs
+    if (fieldDebounceMs && fieldDebounceMs > 0) {
+      if (this.timeoutIds.listeners.change) {
+        clearTimeout(this.timeoutIds.listeners.change)
+        this.abortController.abort()
+      }
+
+      const debouncePromise = new Promise<void>((resolve) => {
+        this.abortController.signal.onabort = () => {
+          resolve()
+        }
+
+        this.collapseController.signal.onabort = () => {
+          this.options.listeners
+            ?.onChangeAsync?.({
+              value: this.state.value,
+              fieldApi: this,
+            })
+            .finally(resolve)
+        }
+
+        this.timeoutIds.listeners.change = setTimeout(() => {
+          this.options.listeners
+            ?.onChangeAsync?.({
+              value: this.state.value,
+              fieldApi: this,
+            })
+            .finally(resolve)
+        }, fieldDebounceMs)
+      }).finally(() => {
+        this.promises.listeners.change = null
+      })
+      this.promises.listeners.change = debouncePromise
+    } else {
+      const promise = this.options.listeners?.onChangeAsync?.({
+        value: this.state.value,
+        fieldApi: this,
+      })
+
+      if (promise) {
+        promise.finally(() => {
+          this.promises.listeners.change = null
+        })
+        this.promises.listeners.change = promise
+      }
+    }
+  }
+
+  collapseFieldOnChangeAsync = () => {
+    if (this.timeoutIds.listeners.change) {
+      clearTimeout(this.timeoutIds.listeners.change)
+    }
+    this.collapseController.abort()
+  }
 }
 
 function normalizeError(rawError?: ValidationError) {

packages/form-core/src/FormApi.ts

@@ -1306,6 +1306,24 @@
     return fieldErrorMapMap.flat()
   }
 
+  collapseAllFieldAsyncOnChange = async () => {
+    const proimises: Promise<void>[] = []
+    batch(() => {
+      void (Object.values(this.fieldInfo) as FieldInfo<any>[]).forEach(
+        (field) => {
+          if (!field.instance) return
+          const promise = field.instance.promises.listeners.change
+          field.instance.collapseFieldOnChangeAsync()
+          if (promise) {
+            proimises.push(promise)
+          }
+        },
+      )
+    })
+
+    await Promise.all(proimises)
+  }
+
   /**
    * Validates the children of a specified array in the form starting from a given index until the end using the correct handlers for a given validation type.
    */
@@ -1770,6 +1788,7 @@
       this.baseStore.setState((prev) => ({ ...prev, isSubmitting: false }))
     }
 
+    await this.collapseAllFieldAsyncOnChange()
     await this.validateAllFields('submit')
 
     if (!this.state.isFieldsValid) {