@tanstack/form-core 1.3.4 → 1.4.0

package/src/FieldApi.ts

@@ -20,6 +20,7 @@ import type {
   FormValidateOrFn,
 } from './FormApi'
 import type {
+  ListenerCause,
   UpdateMetaOptions,
   ValidationCause,
   ValidationError,
@@ -349,7 +350,9 @@ export interface FieldListeners<
   TData extends DeepValue<TParentData, TName> = DeepValue<TParentData, TName>,
 > {
   onChange?: FieldListenerFn<TParentData, TName, TData>
+  onChangeDebounceMs?: number
   onBlur?: FieldListenerFn<TParentData, TName, TData>
+  onBlurDebounceMs?: number
   onMount?: FieldListenerFn<TParentData, TName, TData>
   onSubmit?: FieldListenerFn<TParentData, TName, TData>
 }
@@ -962,7 +965,10 @@ export class FieldApi<
   get state() {
     return this.store.state
   }
-  timeoutIds: Record<ValidationCause, ReturnType<typeof setTimeout> | null>
+  timeoutIds: {
+    validations: Record<ValidationCause, ReturnType<typeof setTimeout> | null>
+    listeners: Record<ListenerCause, ReturnType<typeof setTimeout> | null>
+  }
 
   /**
    * Initializes a new `FieldApi` instance.
@@ -992,7 +998,10 @@ export class FieldApi<
   ) {
     this.form = opts.form as never
     this.name = opts.name as never
-    this.timeoutIds = {} as Record<ValidationCause, never>
+    this.timeoutIds = {
+      validations: {} as Record<ValidationCause, never>,
+      listeners: {} as Record<ListenerCause, never>,
+    }
 
     this.store = new Derived({
       deps: [this.form.store],
@@ -1175,10 +1184,7 @@ export class FieldApi<
   setValue = (updater: Updater<TData>, options?: UpdateMetaOptions) => {
     this.form.setFieldValue(this.name, updater as never, options)
 
-    this.options.listeners?.onChange?.({
-      value: this.state.value,
-      fieldApi: this,
-    })
+    this.triggerOnChangeListener()
 
     this.validate('change')
   }
@@ -1226,10 +1232,7 @@ export class FieldApi<
   ) => {
     this.form.pushFieldValue(this.name, value as any, opts)
 
-    this.options.listeners?.onChange?.({
-      value: this.state.value,
-      fieldApi: this,
-    })
+    this.triggerOnChangeListener()
   }
 
   /**
@@ -1242,10 +1245,7 @@ export class FieldApi<
   ) => {
     this.form.insertFieldValue(this.name, index, value as any, opts)
 
-    this.options.listeners?.onChange?.({
-      value: this.state.value,
-      fieldApi: this,
-    })
+    this.triggerOnChangeListener()
   }
 
   /**
@@ -1258,10 +1258,7 @@ export class FieldApi<
   ) => {
     this.form.replaceFieldValue(this.name, index, value as any, opts)
 
-    this.options.listeners?.onChange?.({
-      value: this.state.value,
-      fieldApi: this,
-    })
+    this.triggerOnChangeListener()
   }
 
   /**
@@ -1270,10 +1267,7 @@ export class FieldApi<
   removeValue = (index: number, opts?: UpdateMetaOptions) => {
     this.form.removeFieldValue(this.name, index, opts)
 
-    this.options.listeners?.onChange?.({
-      value: this.state.value,
-      fieldApi: this,
-    })
+    this.triggerOnChangeListener()
   }
 
   /**
@@ -1282,10 +1276,7 @@ export class FieldApi<
   swapValues = (aIndex: number, bIndex: number, opts?: UpdateMetaOptions) => {
     this.form.swapFieldValues(this.name, aIndex, bIndex, opts)
 
-    this.options.listeners?.onChange?.({
-      value: this.state.value,
-      fieldApi: this,
-    })
+    this.triggerOnChangeListener()
   }
 
   /**
@@ -1294,10 +1285,7 @@ export class FieldApi<
   moveValue = (aIndex: number, bIndex: number, opts?: UpdateMetaOptions) => {
     this.form.moveFieldValues(this.name, aIndex, bIndex, opts)
 
-    this.options.listeners?.onChange?.({
-      value: this.state.value,
-      fieldApi: this,
-    })
+    this.triggerOnChangeListener()
   }
 
   /**
@@ -1502,29 +1490,32 @@ export class FieldApi<
           let rawError!: ValidationError | undefined
           try {
             rawError = await new Promise((rawResolve, rawReject) => {
-              if (this.timeoutIds[validateObj.cause]) {
-                clearTimeout(this.timeoutIds[validateObj.cause]!)
+              if (this.timeoutIds.validations[validateObj.cause]) {
+                clearTimeout(this.timeoutIds.validations[validateObj.cause]!)
               }
 
-              this.timeoutIds[validateObj.cause] = setTimeout(async () => {
-                if (controller.signal.aborted) return rawResolve(undefined)
-                try {
-                  rawResolve(
-                    await this.runValidator({
-                      validate: validateObj.validate,
-                      value: {
-                        value: field.store.state.value,
-                        fieldApi: field,
-                        signal: controller.signal,
-                        validationSource: 'field',
-                      },
-                      type: 'validateAsync',
-                    }),
-                  )
-                } catch (e) {
-                  rawReject(e)
-                }
-              }, validateObj.debounceMs)
+              this.timeoutIds.validations[validateObj.cause] = setTimeout(
+                async () => {
+                  if (controller.signal.aborted) return rawResolve(undefined)
+                  try {
+                    rawResolve(
+                      await this.runValidator({
+                        validate: validateObj.validate,
+                        value: {
+                          value: field.store.state.value,
+                          fieldApi: field,
+                          signal: controller.signal,
+                          validationSource: 'field',
+                        },
+                        type: 'validateAsync',
+                      }),
+                    )
+                  } catch (e) {
+                    rawReject(e)
+                  }
+                },
+                validateObj.debounceMs,
+              )
             })
           } catch (e: unknown) {
             rawError = e as ValidationError
@@ -1633,10 +1624,7 @@ export class FieldApi<
     }
     this.validate('blur')
 
-    this.options.listeners?.onBlur?.({
-      value: this.state.value,
-      fieldApi: this,
-    })
+    this.triggerOnBlurListener()
   }
 
   /**
@@ -1654,6 +1642,50 @@ export class FieldApi<
         }) as never,
     )
   }
+
+  private triggerOnBlurListener() {
+    const debounceMs = this.options.listeners?.onBlurDebounceMs
+
+    if (debounceMs && debounceMs > 0) {
+      if (this.timeoutIds.listeners.blur) {
+        clearTimeout(this.timeoutIds.listeners.blur)
+      }
+
+      this.timeoutIds.listeners.blur = setTimeout(() => {
+        this.options.listeners?.onBlur?.({
+          value: this.state.value,
+          fieldApi: this,
+        })
+      }, debounceMs)
+    } else {
+      this.options.listeners?.onBlur?.({
+        value: this.state.value,
+        fieldApi: this,
+      })
+    }
+  }
+
+  private triggerOnChangeListener() {
+    const debounceMs = this.options.listeners?.onChangeDebounceMs
+
+    if (debounceMs && debounceMs > 0) {
+      if (this.timeoutIds.listeners.change) {
+        clearTimeout(this.timeoutIds.listeners.change)
+      }
+
+      this.timeoutIds.listeners.change = setTimeout(() => {
+        this.options.listeners?.onChange?.({
+          value: this.state.value,
+          fieldApi: this,
+        })
+      }, debounceMs)
+    } else {
+      this.options.listeners?.onChange?.({
+        value: this.state.value,
+        fieldApi: this,
+      })
+    }
+  }
 }
 
 function normalizeError(rawError?: ValidationError) {

package/src/types.ts

@@ -10,6 +10,11 @@ export type ValidationSource = 'form' | 'field'
  */
 export type ValidationCause = 'change' | 'blur' | 'submit' | 'mount' | 'server'
 
+/**
+ * @private
+ */
+export type ListenerCause = 'change' | 'blur' | 'submit' | 'mount'
+
 /**
  * @private
  */