Merge branch 'main' of https://github.com/TanStack/form into reset-form-delete-children

Author: LeCarbonator

docs/framework/react/guides/listeners.md

@@ -67,3 +67,25 @@ function App() {
   )
 }
 ```
+
+### Built-in Debouncing
+
+If you are making an API request inside a listener, you may want to debounce the calls as it can lead to performance issues.
+We enable an easy method for debouncing your listeners by adding a `onChangeDebounceMs` or `onBlurDebounceMs`.
+
+```tsx
+<form.Field
+  name="country"
+  listeners={{
+    onChangeDebounceMs: 500, // 500ms debounce
+    onChange: ({ value }) => {
+      console.log(`Country changed to: ${value} without a change within 500ms, resetting province`)
+      form.setFieldValue('province', '')
+    },
+  }}
+>
+  {(field) => (
+    /* ... */
+  )}
+</form.Field>
+```

docs/reference/classes/fieldapi.md

@@ -7,7 +7,7 @@ title: FieldApi
 
 # Class: FieldApi\<TParentData, TName, TData, TOnMount, TOnChange, TOnChangeAsync, TOnBlur, TOnBlurAsync, TOnSubmit, TOnSubmitAsync, TFormOnMount, TFormOnChange, TFormOnChangeAsync, TFormOnBlur, TFormOnBlurAsync, TFormOnSubmit, TFormOnSubmitAsync, TFormOnServer, TParentSubmitMeta\>
 
-Defined in: [packages/form-core/src/FieldApi.ts:842](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L842)
+Defined in: [packages/form-core/src/FieldApi.ts:845](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L845)
 
 A class representing the API for managing a form field.
 
@@ -65,7 +65,7 @@ the `new FieldApi` constructor.
 new FieldApi<TParentData, TName, TData, TOnMount, TOnChange, TOnChangeAsync, TOnBlur, TOnBlurAsync, TOnSubmit, TOnSubmitAsync, TFormOnMount, TFormOnChange, TFormOnChangeAsync, TFormOnBlur, TFormOnBlurAsync, TFormOnSubmit, TFormOnSubmitAsync, TFormOnServer, TParentSubmitMeta>(opts): FieldApi<TParentData, TName, TData, TOnMount, TOnChange, TOnChangeAsync, TOnBlur, TOnBlurAsync, TOnSubmit, TOnSubmitAsync, TFormOnMount, TFormOnChange, TFormOnChangeAsync, TFormOnBlur, TFormOnBlurAsync, TFormOnSubmit, TFormOnSubmitAsync, TFormOnServer, TParentSubmitMeta>
 ```
 
-Defined in: [packages/form-core/src/FieldApi.ts:970](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L970)
+Defined in: [packages/form-core/src/FieldApi.ts:976](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L976)
 
 Initializes a new `FieldApi` instance.
 
@@ -87,7 +87,7 @@ Initializes a new `FieldApi` instance.
 form: FormApi<TParentData, TFormOnMount, TFormOnChange, TFormOnChangeAsync, TFormOnBlur, TFormOnBlurAsync, TFormOnSubmit, TFormOnSubmitAsync, TFormOnServer, TParentSubmitMeta>;
 ```
 
-Defined in: [packages/form-core/src/FieldApi.ts:886](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L886)
+Defined in: [packages/form-core/src/FieldApi.ts:889](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L889)
 
 A reference to the form API instance.
 
@@ -99,7 +99,7 @@ A reference to the form API instance.
 name: DeepKeys<TParentData>;
 ```
 
-Defined in: [packages/form-core/src/FieldApi.ts:910](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L910)
+Defined in: [packages/form-core/src/FieldApi.ts:913](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L913)
 
 The field name.
 
@@ -111,7 +111,7 @@ The field name.
 options: FieldApiOptions<TParentData, TName, TData, TOnMount, TOnChange, TOnChangeAsync, TOnBlur, TOnBlurAsync, TOnSubmit, TOnSubmitAsync, TFormOnMount, TFormOnChange, TFormOnChangeAsync, TFormOnBlur, TFormOnBlurAsync, TFormOnSubmit, TFormOnSubmitAsync, TFormOnServer, TParentSubmitMeta>;
 ```
 
-Defined in: [packages/form-core/src/FieldApi.ts:914](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L914)
+Defined in: [packages/form-core/src/FieldApi.ts:917](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L917)
 
 The field options.
 
@@ -123,7 +123,7 @@ The field options.
 store: Derived<FieldState<TParentData, TName, TData, TOnMount, TOnChange, TOnChangeAsync, TOnBlur, TOnBlurAsync, TOnSubmit, TOnSubmitAsync, TFormOnMount, TFormOnChange, TFormOnChangeAsync, TFormOnBlur, TFormOnBlurAsync, TFormOnSubmit, TFormOnSubmitAsync>>;
 ```
 
-Defined in: [packages/form-core/src/FieldApi.ts:938](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L938)
+Defined in: [packages/form-core/src/FieldApi.ts:941](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L941)
 
 The field state store.
 
@@ -132,10 +132,22 @@ The field state store.
 ### timeoutIds
 
 ```ts
-timeoutIds: Record<ValidationCause, null | Timeout>;
+timeoutIds: object;
 ```
 
-Defined in: [packages/form-core/src/FieldApi.ts:965](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L965)
+Defined in: [packages/form-core/src/FieldApi.ts:968](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L968)
+
+#### listeners
+
+```ts
+listeners: Record<ListenerCause, null | Timeout>;
+```
+
+#### validations
+
+```ts
+validations: Record<ValidationCause, null | Timeout>;
+```
 
 ## Accessors
 
@@ -147,7 +159,7 @@ Defined in: [packages/form-core/src/FieldApi.ts:965](https://github.com/TanStack
 get state(): FieldState<TParentData, TName, TData, TOnMount, TOnChange, TOnChangeAsync, TOnBlur, TOnBlurAsync, TOnSubmit, TOnSubmitAsync, TFormOnMount, TFormOnChange, TFormOnChangeAsync, TFormOnBlur, TFormOnBlurAsync, TFormOnSubmit, TFormOnSubmitAsync>
 ```
 
-Defined in: [packages/form-core/src/FieldApi.ts:962](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L962)
+Defined in: [packages/form-core/src/FieldApi.ts:965](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L965)
 
 The current field state.
 
@@ -163,7 +175,7 @@ The current field state.
 getInfo(): FieldInfo<TParentData>
 ```
 
-Defined in: [packages/form-core/src/FieldApi.ts:1218](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L1218)
+Defined in: [packages/form-core/src/FieldApi.ts:1224](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L1224)
 
 Gets the field information object.
 
@@ -179,7 +191,7 @@ Gets the field information object.
 getMeta(): FieldMeta<TParentData, TName, TData, TOnMount, TOnChange, TOnChangeAsync, TOnBlur, TOnBlurAsync, TOnSubmit, TOnSubmitAsync, TFormOnMount, TFormOnChange, TFormOnChangeAsync, TFormOnBlur, TFormOnBlurAsync, TFormOnSubmit, TFormOnSubmitAsync>
 ```
 
-Defined in: [packages/form-core/src/FieldApi.ts:1186](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L1186)
+Defined in: [packages/form-core/src/FieldApi.ts:1192](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L1192)
 
 #### Returns
 
@@ -193,7 +205,7 @@ Defined in: [packages/form-core/src/FieldApi.ts:1186](https://github.com/TanStac
 getValue(): TData
 ```
 
-Defined in: [packages/form-core/src/FieldApi.ts:1168](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L1168)
+Defined in: [packages/form-core/src/FieldApi.ts:1177](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L1177)
 
 Gets the current field value.
 
@@ -213,7 +225,7 @@ Use `field.state.value` instead.
 handleBlur(): void
 ```
 
-Defined in: [packages/form-core/src/FieldApi.ts:1625](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L1625)
+Defined in: [packages/form-core/src/FieldApi.ts:1616](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L1616)
 
 Handles the blur event.
 
@@ -229,7 +241,7 @@ Handles the blur event.
 handleChange(updater): void
 ```
 
-Defined in: [packages/form-core/src/FieldApi.ts:1618](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L1618)
+Defined in: [packages/form-core/src/FieldApi.ts:1609](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L1609)
 
 Handles the change event.
 
@@ -254,7 +266,7 @@ insertValue(
    opts?): void
 ```
 
-Defined in: [packages/form-core/src/FieldApi.ts:1238](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L1238)
+Defined in: [packages/form-core/src/FieldApi.ts:1241](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L1241)
 
 Inserts a value at the specified index, shifting the subsequent values to the right.
 
@@ -284,7 +296,7 @@ Inserts a value at the specified index, shifting the subsequent values to the ri
 mount(): () => void
 ```
 
-Defined in: [packages/form-core/src/FieldApi.ts:1063](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L1063)
+Defined in: [packages/form-core/src/FieldApi.ts:1072](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L1072)
 
 Mounts the field instance to the form.
 
@@ -307,7 +319,7 @@ moveValue(
    opts?): void
 ```
 
-Defined in: [packages/form-core/src/FieldApi.ts:1294](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L1294)
+Defined in: [packages/form-core/src/FieldApi.ts:1285](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L1285)
 
 Moves the value at the first specified index to the second specified index.
 
@@ -337,7 +349,7 @@ Moves the value at the first specified index to the second specified index.
 pushValue(value, opts?): void
 ```
 
-Defined in: [packages/form-core/src/FieldApi.ts:1223](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L1223)
+Defined in: [packages/form-core/src/FieldApi.ts:1229](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L1229)
 
 Pushes a new value to the field.
 
@@ -363,7 +375,7 @@ Pushes a new value to the field.
 removeValue(index, opts?): void
 ```
 
-Defined in: [packages/form-core/src/FieldApi.ts:1270](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L1270)
+Defined in: [packages/form-core/src/FieldApi.ts:1267](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L1267)
 
 Removes a value at the specified index.
 
@@ -422,7 +434,7 @@ Replaces a value at the specified index.
 setErrorMap(errorMap): void
 ```
 
-Defined in: [packages/form-core/src/FieldApi.ts:1645](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L1645)
+Defined in: [packages/form-core/src/FieldApi.ts:1633](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L1633)
 
 Updates the field's errorMap
 
@@ -444,7 +456,7 @@ Updates the field's errorMap
 setMeta(updater): void
 ```
 
-Defined in: [packages/form-core/src/FieldApi.ts:1191](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L1191)
+Defined in: [packages/form-core/src/FieldApi.ts:1197](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L1197)
 
 Sets the field metadata.
 
@@ -466,7 +478,7 @@ Sets the field metadata.
 setValue(updater, options?): void
 ```
 
-Defined in: [packages/form-core/src/FieldApi.ts:1175](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L1175)
+Defined in: [packages/form-core/src/FieldApi.ts:1184](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L1184)
 
 Sets the field value and run the `change` validator.
 
@@ -495,7 +507,7 @@ swapValues(
    opts?): void
 ```
 
-Defined in: [packages/form-core/src/FieldApi.ts:1282](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L1282)
+Defined in: [packages/form-core/src/FieldApi.ts:1276](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L1276)
 
 Swaps the values at the specified indices.
 
@@ -525,7 +537,7 @@ Swaps the values at the specified indices.
 update(opts): void
 ```
 
-Defined in: [packages/form-core/src/FieldApi.ts:1111](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L1111)
+Defined in: [packages/form-core/src/FieldApi.ts:1120](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L1120)
 
 Updates the field instance with new options.
 
@@ -547,7 +559,7 @@ Updates the field instance with new options.
 validate(cause, opts?): unknown[] | Promise<unknown[]>
 ```
 
-Defined in: [packages/form-core/src/FieldApi.ts:1585](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L1585)
+Defined in: [packages/form-core/src/FieldApi.ts:1576](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L1576)
 
 Validates the field value.
 

docs/reference/classes/formapi.md

@@ -350,7 +350,7 @@ Defined in: [packages/form-core/src/FormApi.ts:1816](https://github.com/TanStack
 
 ##### value
 
-[`DeepValue`](../type-aliases/deepvalue.md)\<`TFormData`, `TField`\> *extends* `any`[] ? [`DeepValue`](../type-aliases/deepvalue.md)\<`TFormData`, `TField`\>\[`number`\] : `never`
+[`DeepValue`](../type-aliases/deepvalue.md)\<`TFormData`, `TField`\> *extends* `any`[] ? `any`[] & [`DeepValue`](../type-aliases/deepvalue.md)\<`TFormData`, `TField`\>\[`number`\] : `never`
 
 ##### opts?
 
@@ -447,7 +447,7 @@ Pushes a value into an array field.
 
 ##### value
 
-[`DeepValue`](../type-aliases/deepvalue.md)\<`TFormData`, `TField`\> *extends* `any`[] ? [`DeepValue`](../type-aliases/deepvalue.md)\<`TFormData`, `TField`\>\[`number`\] : `never`
+[`DeepValue`](../type-aliases/deepvalue.md)\<`TFormData`, `TField`\> *extends* `any`[] ? `any`[] & [`DeepValue`](../type-aliases/deepvalue.md)\<`TFormData`, `TField`\>\[`number`\] : `never`
 
 ##### opts?
 
@@ -526,7 +526,7 @@ Replaces a value into an array field at the specified index.
 
 ##### value
 
-[`DeepValue`](../type-aliases/deepvalue.md)\<`TFormData`, `TField`\> *extends* `any`[] ? [`DeepValue`](../type-aliases/deepvalue.md)\<`TFormData`, `TField`\>\[`number`\] : `never`
+[`DeepValue`](../type-aliases/deepvalue.md)\<`TFormData`, `TField`\> *extends* `any`[] ? `any`[] & [`DeepValue`](../type-aliases/deepvalue.md)\<`TFormData`, `TField`\>\[`number`\] : `never`
 
 ##### opts?
 

docs/reference/index.md

@@ -14,14 +14,19 @@ title: "@tanstack/form-core"
 
 ## Interfaces
 
+- [AnyDeepKeyAndValue](interfaces/anydeepkeyandvalue.md)
+- [ArrayDeepKeyAndValue](interfaces/arraydeepkeyandvalue.md)
 - [FieldApiOptions](interfaces/fieldapioptions.md)
 - [FieldListeners](interfaces/fieldlisteners.md)
 - [FieldOptions](interfaces/fieldoptions.md)
 - [FieldValidators](interfaces/fieldvalidators.md)
 - [FormOptions](interfaces/formoptions.md)
 - [FormState](interfaces/formstate.md)
 - [FormValidators](interfaces/formvalidators.md)
+- [ObjectDeepKeyAndValue](interfaces/objectdeepkeyandvalue.md)
 - [StandardSchemaV1Issue](interfaces/standardschemav1issue.md)
+- [TupleDeepKeyAndValue](interfaces/tupledeepkeyandvalue.md)
+- [UnknownDeepKeyAndValue](interfaces/unknowndeepkeyandvalue.md)
 
 ## Type Aliases
 
@@ -35,12 +40,13 @@ title: "@tanstack/form-core"
 - [AnyFormState](type-aliases/anyformstate.md)
 - [ArrayAccessor](type-aliases/arrayaccessor.md)
 - [BaseFormState](type-aliases/baseformstate.md)
+- [DeepKeyAndValueArray](type-aliases/deepkeyandvaluearray.md)
+- [DeepKeyAndValueObject](type-aliases/deepkeyandvalueobject.md)
+- [DeepKeyAndValueTuple](type-aliases/deepkeyandvaluetuple.md)
+- [DeepKeyAndValueUnknown](type-aliases/deepkeyandvalueunknown.md)
 - [DeepKeys](type-aliases/deepkeys.md)
+- [DeepKeysAndValues](type-aliases/deepkeysandvalues.md)
 - [DeepRecord](type-aliases/deeprecord.md)
-- [DeepRecordArrayUnion](type-aliases/deeprecordarrayunion.md)
-- [DeepRecordObjectUnion](type-aliases/deeprecordobjectunion.md)
-- [DeepRecordTupleUnion](type-aliases/deeprecordtupleunion.md)
-- [DeepRecordUnion](type-aliases/deeprecordunion.md)
 - [DeepValue](type-aliases/deepvalue.md)
 - [DerivedFormState](type-aliases/derivedformstate.md)
 - [FieldInfo](type-aliases/fieldinfo.md)
@@ -51,10 +57,12 @@ title: "@tanstack/form-core"
 - [FormValidateFn](type-aliases/formvalidatefn.md)
 - [FormValidationError](type-aliases/formvalidationerror.md)
 - [FormValidator](type-aliases/formvalidator.md)
+- [Nullable](type-aliases/nullable.md)
 - [ObjectAccessor](type-aliases/objectaccessor.md)
 - [StandardSchemaV1](type-aliases/standardschemav1.md)
 - [TStandardSchemaValidatorValue](type-aliases/tstandardschemavalidatorvalue.md)
 - [TupleAccessor](type-aliases/tupleaccessor.md)
+- [UnknownAccessor](type-aliases/unknownaccessor.md)
 - [UnwrapFieldAsyncValidateOrFn](type-aliases/unwrapfieldasyncvalidateorfn.md)
 - [UnwrapFieldValidateOrFn](type-aliases/unwrapfieldvalidateorfn.md)
 - [UnwrapFormAsyncValidateOrFn](type-aliases/unwrapformasyncvalidateorfn.md)

docs/reference/interfaces/anydeepkeyandvalue.md

@@ -0,0 +1,30 @@
+---
+id: AnyDeepKeyAndValue
+title: AnyDeepKeyAndValue
+---
+
+<!-- DO NOT EDIT: this page is autogenerated from the type comments -->
+
+# Interface: AnyDeepKeyAndValue
+
+Defined in: [packages/form-core/src/util-types.ts:24](https://github.com/TanStack/form/blob/main/packages/form-core/src/util-types.ts#L24)
+
+## Properties
+
+### key
+
+```ts
+key: string;
+```
+
+Defined in: [packages/form-core/src/util-types.ts:25](https://github.com/TanStack/form/blob/main/packages/form-core/src/util-types.ts#L25)
+
+***
+
+### value
+
+```ts
+value: any;
+```
+
+Defined in: [packages/form-core/src/util-types.ts:26](https://github.com/TanStack/form/blob/main/packages/form-core/src/util-types.ts#L26)