fix: make validateField return type consistent

.changeset/nine-adults-turn.md

@@ -0,0 +1,9 @@
+---
+'formik': patch
+---
+
+The validateField function now consistently returns Promise<string | undefined> across all validation paths, where `string` represents a validation error message, `undefined` represents a successful validation.
+
+while previous implementation:
+- validation via `<Field validate={...}>` returned Promise<string | undefined>
+- validation via schema returned Promise<void>

docs/api/formik.md

@@ -245,7 +245,7 @@ component.
 
 Imperatively call your `validate` or `validateSchema` depending on what was specified. You can optionally pass values to validate against and this modify Formik state accordingly, otherwise this will use the current `values` of the form.
 
-#### `validateField: (field: string) => void`
+#### `validateField: (field: string) => Promise<string | undefined>`
 
 Imperatively call field's `validate` function if specified for given field or run schema validation using [Yup's `schema.validateAt`](https://github.com/jquense/yup#mixedvalidateatpath-string-value-any-options-object-promiseany-validationerror) and the provided top-level `validationSchema` prop. Formik will use the current field value.
 

packages/formik/src/Formik.tsx

@@ -484,11 +484,10 @@ export function useFormik<Values extends FormikValues = FormikValues>({
     }
   }, [enableReinitialize, props.initialStatus, props.initialTouched]);
 
-  const validateField = useEventCallback((name: string) => {
+  const validateField = useEventCallback((name: string): Promise<string | undefined> => {
     // This will efficiently validate a single field by avoiding state
     // changes if the validation function is synchronous. It's different from
     // what is called when using validateForm.
-
     if (
       fieldRegistry.current[name] &&
       isFunction(fieldRegistry.current[name].validate)
@@ -506,6 +505,7 @@ export function useFormik<Values extends FormikValues = FormikValues>({
               payload: { field: name, value: error },
             });
             dispatch({ type: 'SET_ISVALIDATING', payload: false });
+            return error;
           });
       } else {
         dispatch({
@@ -522,15 +522,17 @@ export function useFormik<Values extends FormikValues = FormikValues>({
       return runValidationSchema(state.values, name)
         .then((x: any) => x)
         .then((error: any) => {
+          const fieldError = getIn(error, name);
           dispatch({
             type: 'SET_FIELD_ERROR',
-            payload: { field: name, value: getIn(error, name) },
+            payload: { field: name, value: fieldError },
           });
           dispatch({ type: 'SET_ISVALIDATING', payload: false });
-        });
+          return fieldError
+        })
     }
 
-    return Promise.resolve();
+    return Promise.resolve(undefined);
   });
 
   const registerField = React.useCallback((name: string, { validate }: any) => {

packages/formik/src/types.tsx

@@ -109,7 +109,7 @@ export interface FormikHelpers<Values> {
   /** Validate form values */
   validateForm: (values?: any) => Promise<FormikErrors<Values>>;
   /** Validate field value */
-  validateField: (field: string) => Promise<void> | Promise<string | undefined>;
+  validateField: (field: string) => Promise<string | undefined>;
   /** Reset form */
   resetForm: (nextState?: Partial<FormikState<Values>>) => void;
   /** Submit the form imperatively */

packages/formik/test/Field.test.tsx

@@ -385,15 +385,16 @@ describe('Field / FastField', () => {
           component: 'input',
         });
         rerender();
-
-        act(() => {
-          getFormProps().validateField('name');
+        
+        const error = await act(async () => {
+          return await getFormProps().validateField('name');
         });
 
         rerender();
         await waitFor(() => {
           expect(validate).toHaveBeenCalled();
           expect(getFormProps().errors.name).toBe('Error!');
+          expect(error).toBe('Error!');
         });
       }
     );
@@ -408,12 +409,15 @@ describe('Field / FastField', () => {
         // workaround for `useEffect` to run: https://github.com/facebook/react/issues/14050
         rerender();
 
-        act(() => {
-          getFormProps().validateField('name');
+        const error = await act(async () => {
+          return await getFormProps().validateField('name');
         });
 
         expect(validate).toHaveBeenCalled();
-        await waitFor(() => expect(getFormProps().errors.name).toBe('Error!'));
+        await waitFor(() => {
+          expect(getFormProps().errors.name).toBe('Error!')
+          expect(error).toBe('Error!')
+        });
       }
     );
 
@@ -432,15 +436,16 @@ describe('Field / FastField', () => {
 
         rerender();
 
-        act(() => {
-          getFormProps().validateField('name');
+        const error = await act(async () => {
+          return await getFormProps().validateField('name');
         });
 
-        await waitFor(() =>
+        await waitFor(() => {
           expect(getFormProps().errors).toEqual({
             name: errorMessage,
           })
-        );
+          expect(error).toBe(errorMessage)
+        });
       }
     );
 
@@ -460,13 +465,12 @@ describe('Field / FastField', () => {
 
         rerender();
 
-        act(() => {
-          getFormProps().validateField('user.name');
-        });
+        const error = await act(async () => await getFormProps().validateField('user.name'));
 
-        await waitFor(() =>
+        await waitFor(() => {
           expect(getFormProps().errors).toEqual({ user: { name: 'required' } })
-        );
+          expect(error).toBe('required')
+        });
       }
     );
   });