fix(form-core): Prevent synchronous validators from returning Promises

Passing an asynchronous function to a synchronous validator (i.e.: `onBlur`, `onChange`,
`onDynamic`, `onSubmit`) is a bit of a foot-gun given that it does not produce any typescript
errors, but it also results in the form/field validation function running after the core
validation logic.

To prevent this, update the types for these validator functions on both `FormApi` and
`FieldApi` to prevent passing a function that returns a `Promise`.

Author: mhuggins

.changeset/silver-mails-play.md

@@ -0,0 +1,5 @@
+---
+'@tanstack/form-core': patch
+---
+
+Prevent synchronous validators from returning Promises

docs/reference/type-aliases/UnwrapFieldValidateOrFn.md

@@ -9,7 +9,7 @@ title: UnwrapFieldValidateOrFn
 type UnwrapFieldValidateOrFn<TName, TValidateOrFn, TFormValidateOrFn> = 
   | [TFormValidateOrFn] extends [StandardSchemaV1<any, infer TStandardOut>] ? TName extends keyof TStandardOut ? StandardSchemaV1Issue[] : undefined : undefined
   | UnwrapFormValidateOrFnForInner<TFormValidateOrFn> extends infer TFormValidateVal ? TFormValidateVal extends object ? [DeepValue<TFormValidateVal, TName>] extends [never] ? undefined : StandardSchemaV1Issue[] : TFormValidateVal extends object ? TName extends keyof TFormValidateVal["fields"] ? TFormValidateVal["fields"][TName] : undefined : undefined : never
-  | [TValidateOrFn] extends [FieldValidateFn<any, any, any>] ? ReturnType<TValidateOrFn> : [TValidateOrFn] extends [StandardSchemaV1<any, any>] ? StandardSchemaV1Issue[] : undefined;
+  | [TValidateOrFn] extends [FieldValidateFn<any, any, any, any>] ? ReturnType<TValidateOrFn> : [TValidateOrFn] extends [StandardSchemaV1<any, any>] ? StandardSchemaV1Issue[] : undefined;
 ```
 
 Defined in: [packages/form-core/src/FieldApi.ts:135](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L135)

packages/form-core/src/FieldApi.ts

@@ -13,7 +13,12 @@ import {
   mergeOpts,
 } from './utils'
 import { defaultValidationLogic } from './ValidationLogic'
-import type { DeepKeys, DeepValue, UnwrapOneLevelOfArray } from './util-types'
+import type {
+  DeepKeys,
+  DeepValue,
+  RejectPromiseValidator,
+  UnwrapOneLevelOfArray,
+} from './util-types'
 import type {
   StandardSchemaV1,
   StandardSchemaV1Issue,
@@ -309,13 +314,13 @@ export interface FieldValidators<
   /**
    * An optional function, that runs on the mount event of input.
    */
-  onMount?: TOnMount
+  onMount?: RejectPromiseValidator<TOnMount>
   /**
    * An optional function, that runs on the change event of input.
    *
    * @example z.string().min(1)
    */
-  onChange?: TOnChange
+  onChange?: RejectPromiseValidator<TOnChange>
   /**
    * An optional property similar to `onChange` but async validation
    *
@@ -337,7 +342,7 @@ export interface FieldValidators<
    *
    * @example z.string().min(1)
    */
-  onBlur?: TOnBlur
+  onBlur?: RejectPromiseValidator<TOnBlur>
   /**
    * An optional property similar to `onBlur` but async validation.
    *
@@ -360,14 +365,14 @@ export interface FieldValidators<
    *
    * @example z.string().min(1)
    */
-  onSubmit?: TOnSubmit
+  onSubmit?: RejectPromiseValidator<TOnSubmit>
   /**
    * An optional property similar to `onSubmit` but async validation.
    *
    * @example z.string().refine(async (val) => val.length > 3, { message: 'Testing 123' })
    */
   onSubmitAsync?: TOnSubmitAsync
-  onDynamic?: TOnDynamic
+  onDynamic?: RejectPromiseValidator<TOnDynamic>
   onDynamicAsync?: TOnDynamicAsync
   onDynamicAsyncDebounceMs?: number
 }

packages/form-core/src/FormApi.ts

@@ -47,7 +47,12 @@ import type {
   ValidationErrorMap,
   ValidationErrorMapKeys,
 } from './types'
-import type { DeepKeys, DeepKeysOfType, DeepValue } from './util-types'
+import type {
+  DeepKeys,
+  DeepKeysOfType,
+  DeepValue,
+  RejectPromiseValidator,
+} from './util-types'
 import type { Updater } from './utils'
 
 /**
@@ -186,11 +191,11 @@ export interface FormValidators<
   /**
    * Optional function that fires as soon as the component mounts.
    */
-  onMount?: TOnMount
+  onMount?: RejectPromiseValidator<TOnMount>
   /**
    * Optional function that checks the validity of your data whenever a value changes
    */
-  onChange?: TOnChange
+  onChange?: RejectPromiseValidator<TOnChange>
   /**
    * Optional onChange asynchronous counterpart to onChange. Useful for more complex validation logic that might involve server requests.
    */
@@ -202,7 +207,7 @@ export interface FormValidators<
   /**
    * Optional function that validates the form data when a field loses focus, returns a `FormValidationError`
    */
-  onBlur?: TOnBlur
+  onBlur?: RejectPromiseValidator<TOnBlur>
   /**
    * Optional onBlur asynchronous validation method for when a field loses focus returns a ` FormValidationError` or a promise of `Promise<FormValidationError>`
    */
@@ -211,9 +216,9 @@ export interface FormValidators<
    * The default time in milliseconds that if set to a number larger than 0, will debounce the async validation event by this length of time in milliseconds.
    */
   onBlurAsyncDebounceMs?: number
-  onSubmit?: TOnSubmit
+  onSubmit?: RejectPromiseValidator<TOnSubmit>
   onSubmitAsync?: TOnSubmitAsync
-  onDynamic?: TOnDynamic
+  onDynamic?: RejectPromiseValidator<TOnDynamic>
   onDynamicAsync?: TOnDynamicAsync
   onDynamicAsyncDebounceMs?: number
 }

packages/form-core/src/util-types.ts

@@ -3,6 +3,23 @@
  */
 export type UnwrapOneLevelOfArray<T> = T extends (infer U)[] ? U : T
 
+/**
+ * @private
+ * Helper type that rejects synchronous validators that return Promises.
+ * If the validator is a function returning a Promise, the type becomes `never`.
+ * Uses infer to extract the return type and handles `any` specially to avoid
+ * rejecting mock functions and other uses of `any`.
+ */
+export type RejectPromiseValidator<T> = T extends (...args: any[]) => infer R
+  ? // Check if R is `any` - if so, allow it (common with mocks)
+    0 extends 1 & R
+    ? T
+    : // Otherwise, reject if it's a Promise
+      [R] extends [Promise<any> | PromiseLike<any>]
+      ? never
+      : T
+  : T
+
 type Narrowable = string | number | bigint | boolean
 
 type NarrowRaw<A> =

packages/form-core/tests/FieldApi.test-d.ts

@@ -1,7 +1,11 @@
 import { expectTypeOf, it } from 'vitest'
 import { z } from 'zod'
-import { FieldApi, FormApi } from '../src/index'
-import type { StandardSchemaV1Issue } from '../src/index'
+import {
+  FieldApi,
+  FieldValidateFn,
+  FormApi,
+  StandardSchemaV1Issue,
+} from '../src/index'
 
 it('should type value properly', () => {
   const form = new FormApi({
@@ -460,3 +464,25 @@ it('should allow setting manual errors with standard schema validators on the fi
     onDynamic: undefined
   }>
 })
+
+it('should not allow promises to be returned from synchronous validators', () => {
+  const form = new FormApi({
+    defaultValues: { name: '' },
+  })
+
+  // This should cause a type error - Promise returns are not allowed in sync validators
+  new FieldApi({
+    form,
+    name: 'name',
+    validators: {
+      // @ts-expect-error synchronous validators should not return promises
+      onBlur: () => Promise.resolve('error'),
+      // @ts-expect-error synchronous validators should not return promises
+      onChange: () => Promise.resolve('error'),
+      // @ts-expect-error synchronous validators should not return promises
+      onDynamic: () => Promise.resolve('error'),
+      // @ts-expect-error synchronous validators should not return promises
+      onChange: () => Promise.resolve('error'),
+    },
+  })
+})

packages/form-core/tests/FormApi.test-d.ts

@@ -447,3 +447,19 @@ it('listeners should be typed correctly when using formOptions', () => {
 
   form.handleSubmit()
 })
+
+it('should not allow promises to be returned from synchronous validators', () => {
+  const form = new FormApi({
+    defaultValues: { name: '' },
+    validators: {
+      // @ts-expect-error synchronous validators should not return promises
+      onBlur: () => Promise.resolve('error'),
+      // @ts-expect-error synchronous validators should not return promises
+      onChange: () => Promise.resolve('error'),
+      // @ts-expect-error synchronous validators should not return promises
+      onDynamic: () => Promise.resolve('error'),
+      // @ts-expect-error synchronous validators should not return promises
+      onChange: () => Promise.resolve('error'),
+    },
+  })
+})