@tanstack/form-core 1.3.2 → 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
  */

package/src/util-types.ts

@@ -21,35 +21,58 @@ export type Narrow<A> = Try<A, [], NarrowRaw<A>>
 
 type IsAny<T> = 0 extends 1 & T ? true : false
 
-export type ArrayAccessor<TPrefix extends string> = `${TPrefix}[${number}]`
+export interface AnyDeepKeyAndValue {
+  key: string
+  value: any
+}
+
+export type ArrayAccessor<TParent extends AnyDeepKeyAndValue> =
+  `${TParent['key'] extends never ? '' : TParent['key']}[${number}]`
+
+export interface ArrayDeepKeyAndValue<
+  in out TParent extends AnyDeepKeyAndValue,
+  in out T extends ReadonlyArray<any>,
+> {
+  key: ArrayAccessor<TParent>
+  value: T[number] | Nullable<TParent['value']>
+}
 
-export type DeepRecordArrayUnion<
+export type DeepKeyAndValueArray<
+  TParent extends AnyDeepKeyAndValue,
   T extends ReadonlyArray<any>,
-  TPrefix extends string,
   TAcc,
-> = DeepRecordUnion<
-  T[number],
-  ArrayAccessor<TPrefix>,
-  TAcc | Record<ArrayAccessor<TPrefix>, T[number]>
+> = DeepKeysAndValues<
+  NonNullable<T[number]>,
+  ArrayDeepKeyAndValue<TParent, T>,
+  TAcc | ArrayDeepKeyAndValue<TParent, T>
 >
 
 export type TupleAccessor<
-  TPrefix extends string,
-  TKey,
-> = `${TPrefix}[${TKey & string}]`
+  TParent extends AnyDeepKeyAndValue,
+  TKey extends string,
+> = `${TParent['key'] extends never ? '' : TParent['key']}[${TKey}]`
+
+export interface TupleDeepKeyAndValue<
+  in out TParent extends AnyDeepKeyAndValue,
+  in out T,
+  in out TKey extends AllTupleKeys<T>,
+> {
+  key: TupleAccessor<TParent, TKey>
+  value: T[TKey] | Nullable<TParent['value']>
+}
 
 export type AllTupleKeys<T> = T extends any ? keyof T & `${number}` : never
 
-export type DeepRecordTupleUnion<
+export type DeepKeyAndValueTuple<
+  TParent extends AnyDeepKeyAndValue,
   T extends ReadonlyArray<any>,
-  TPrefix extends string,
   TAcc,
   TAllKeys extends AllTupleKeys<T> = AllTupleKeys<T>,
 > = TAllKeys extends any
-  ? DeepRecordUnion<
-      T[TAllKeys],
-      TupleAccessor<TPrefix, TAllKeys>,
-      TAcc | Record<TupleAccessor<TPrefix, TAllKeys>, T[TAllKeys]>
+  ? DeepKeysAndValues<
+      NonNullable<T[TAllKeys]>,
+      TupleDeepKeyAndValue<TParent, T, TAllKeys>,
+      TAcc | TupleDeepKeyAndValue<TParent, T, TAllKeys>
     >
   : never
 
@@ -58,53 +81,85 @@ export type AllObjectKeys<T> = T extends any
   : never
 
 export type ObjectAccessor<
-  TPrefix extends string,
+  TParent extends AnyDeepKeyAndValue,
   TKey extends string | number,
-> = TPrefix extends '' ? `${TKey}` : `${TPrefix}.${TKey}`
+> = TParent['key'] extends never ? `${TKey}` : `${TParent['key']}.${TKey}`
+
+export type Nullable<T> = T & (undefined | null)
+
+export interface ObjectDeepKeyAndValue<
+  in out TParent extends AnyDeepKeyAndValue,
+  in out T,
+  in out TKey extends AllObjectKeys<T>,
+> {
+  key: ObjectAccessor<TParent, TKey>
+  value: T[TKey] | Nullable<TParent['value']>
+}
 
-export type DeepRecordObjectUnion<
+export type DeepKeyAndValueObject<
+  TParent extends AnyDeepKeyAndValue,
   T,
-  TPrefix extends string,
   TAcc,
   TAllKeys extends AllObjectKeys<T> = AllObjectKeys<T>,
 > = TAllKeys extends any
-  ? DeepRecordUnion<
-      T[TAllKeys],
-      ObjectAccessor<TPrefix, TAllKeys>,
-      TAcc | Record<ObjectAccessor<TPrefix, TAllKeys>, T[TAllKeys]>
+  ? DeepKeysAndValues<
+      NonNullable<T[TAllKeys]>,
+      ObjectDeepKeyAndValue<TParent, T, TAllKeys>,
+      TAcc | ObjectDeepKeyAndValue<TParent, T, TAllKeys>
     >
   : never
 
-export type DeepRecordUnion<T, TPrefix extends string = '', TAcc = never> =
+export type UnknownAccessor<TParent extends AnyDeepKeyAndValue> =
+  TParent['key'] extends never ? string : `${TParent['key']}.${string}`
+
+export interface UnknownDeepKeyAndValue<TParent extends AnyDeepKeyAndValue> {
+  key: UnknownAccessor<TParent>
+  value: unknown
+}
+
+export type DeepKeyAndValueUnknown<TParent extends AnyDeepKeyAndValue> =
+  UnknownDeepKeyAndValue<TParent>
+
+export type DeepKeysAndValues<
+  T,
+  TParent extends AnyDeepKeyAndValue = never,
+  TAcc = never,
+> =
   IsAny<T> extends true
     ? T
     : T extends string | number | boolean | bigint | Date
       ? TAcc
       : T extends ReadonlyArray<any>
         ? number extends T['length']
-          ? DeepRecordArrayUnion<T, TPrefix, TAcc>
-          : DeepRecordTupleUnion<T, TPrefix, TAcc>
-        : T extends object
-          ? DeepRecordObjectUnion<T, TPrefix, TAcc>
-          : TAcc
+          ? DeepKeyAndValueArray<TParent, T, TAcc>
+          : DeepKeyAndValueTuple<TParent, T, TAcc>
+        : keyof T extends never
+          ? TAcc | DeepKeyAndValueUnknown<TParent>
+          : T extends object
+            ? DeepKeyAndValueObject<TParent, T, TAcc>
+            : TAcc
 
 export type DeepRecord<T> = {
-  [TRecord in DeepRecordUnion<T> as keyof TRecord]: TRecord[keyof TRecord]
+  [TRecord in DeepKeysAndValues<T> extends AnyDeepKeyAndValue
+    ? DeepKeysAndValues<T>
+    : never as TRecord['key']]: TRecord['value']
 }
 
-type UnionKeys<T> = T extends any ? keyof T : never
-
 /**
  * The keys of an object or array, deeply nested.
  */
 export type DeepKeys<T> = unknown extends T
   ? string
-  : UnionKeys<DeepRecordUnion<T>> & string
+  : DeepKeysAndValues<T> extends AnyDeepKeyAndValue
+    ? DeepKeysAndValues<T>['key']
+    : never
 
 /**
  * Infer the type of a deeply nested property within an object or an array.
  */
 export type DeepValue<TValue, TAccessor> =
   DeepRecord<TValue> extends infer TDeepRecord
-    ? TDeepRecord[TAccessor & keyof TDeepRecord]
+    ? TAccessor extends keyof TDeepRecord
+      ? TDeepRecord[TAccessor]
+      : never
     : never